Retrieves or displays a list of pages (or hierarchical post type items) in list (li) format.

Description

See also

• get_pages()

Parameters

$argsarray|stringoptional

Array or string of arguments to generate a list of pages. See get_pages() for additional arguments.

• child_of int
  Display only the sub-pages of a single page by ID. Default 0 (all pages).
• authors string
  Comma-separated list of author IDs. Default empty (all authors).
• date_format string
  PHP date format to use for the listed pages. Relies on the 'show_date' parameter.
  Default is the value of 'date_format' option.
• depth int
  Number of levels in the hierarchy of pages to include in the generated list.
  Accepts -1 (any depth), 0 (all pages), 1 (top-level pages only), and n (pages to the given n depth). Default 0.
• echo bool
  Whether or not to echo the list of pages. Default true.
• exclude string
  Comma-separated list of page IDs to exclude.
• include array
  Comma-separated list of page IDs to include.
• link_after string
  Text or HTML to follow the page link label. Default null.
• link_before string
  Text or HTML to precede the page link label. Default null.
• post_type string
  Post type to query for. Default 'page'.
• post_status string|array
  Comma-separated list or array of post statuses to include. Default 'publish'.
• show_date string
  Whether to display the page publish or modified date for each page. Accepts 'modified' or any other value. An empty value hides the date.
• sort_column string
  Comma-separated list of column names to sort the pages by. Accepts 'post_author', 'post_date', 'post_title', 'post_name', 'post_modified', 'post_modified_gmt', 'menu_order', 'post_parent', 'ID', 'rand', or 'comment_count'. Default 'post_title'.
• title_li string
  List heading. Passing a null or empty value will result in no heading, and the list will not be wrapped with unordered list <ul> tags. Default 'Pages'.
• item_spacing string
  Whether to preserve whitespace within the menu’s HTML. Accepts 'preserve' or 'discard'.
  Default 'preserve'.
• walker Walker
  Walker instance to use for listing pages. Default empty which results in a Walker_Page instance being used.

More Arguments from get_pages( … $args )

Array or string of arguments to retrieve pages.

• child_of int
  Page ID to return child and grandchild pages of. Note: The value of $hierarchical has no bearing on whether $child_of returns hierarchical results. Default 0, or no restriction.
• sort_order string
  How to sort retrieved pages. Accepts 'ASC', 'DESC'. Default 'ASC'.
• sort_column string
  What columns to sort pages by, comma-separated. Accepts 'post_author', 'post_date', 'post_title', 'post_name', 'post_modified', 'menu_order', 'post_modified_gmt', 'post_parent', 'ID', 'rand', 'comment*count'.
  'post*' can be omitted for any values that start with it.
  Default 'post_title'.
• hierarchical bool
  Whether to return pages hierarchically. If false in conjunction with $child_of also being false, both arguments will be disregarded.
  Default true.
• exclude int[]
  Array of page IDs to exclude.
• include int[]
  Array of page IDs to include. Cannot be used with $child_of, $parent, $exclude, $meta_key, $meta_value, or $hierarchical.
  
• meta_key string
  Only include pages with this meta key.
• meta_value string
  Only include pages with this meta value. Requires $meta_key.
  
• authors string
  A comma-separated list of author IDs.
• parent int
  Page ID to return direct children of. Default -1, or no restriction.
• exclude_tree string|int[]
  Comma-separated string or array of page IDs to exclude.
  
• number int
  The number of pages to return. Default 0, or all pages.
• offset int
  The number of pages to skip before returning. Requires $number.
  Default 0.
• post_type string
  The post type to query. Default 'page'.
• post_status string|array
  A comma-separated list or array of post statuses to include.
  Default 'publish'.

Default:''

Return

More Information

Menu Item CSS Classes

The following classes are applied to menu items, i.e. to the HTML <li> tags, generated by wp_list_pages() . Note: The wp_list_pages() and wp_page_menu() functions output the same CSS classes.

All Menu Items

• .page_item
  This class is added to menu items that correspond to a static page.
• .page-item-$ID
  This class is added to menu items that correspond to a static page, where $ID is the static page ID.

Current-Page Menu Items

• .current_page_item
  This class is added to menu items that correspond to the currently rendered static page.

Current-Page Parent Menu Items

• .current_page_parent
  This class is added to menu items that correspond to the hierarchical parent of the currently rendered static page.

Current-Page Ancestor Menu Items

• .current_page_ancestor
  This class is added to menu items that correspond to a hierarchical ancestor of the currently rendered static page.

Source

function wp_list_pages( $args = '' ) {
	$defaults = array(
		'depth'        => 0,
		'show_date'    => '',
		'date_format'  => get_option( 'date_format' ),
		'child_of'     => 0,
		'exclude'      => '',
		'title_li'     => __( 'Pages' ),
		'echo'         => 1,
		'authors'      => '',
		'sort_column'  => 'menu_order, post_title',
		'link_before'  => '',
		'link_after'   => '',
		'item_spacing' => 'preserve',
		'walker'       => '',
	);

	$parsed_args = wp_parse_args( $args, $defaults );

	if ( ! in_array( $parsed_args['item_spacing'], array( 'preserve', 'discard' ), true ) ) {
		// Invalid value, fall back to default.
		$parsed_args['item_spacing'] = $defaults['item_spacing'];
	}

	$output       = '';
	$current_page = 0;

	// Sanitize, mostly to keep spaces out.
	$parsed_args['exclude'] = preg_replace( '/[^0-9,]/', '', $parsed_args['exclude'] );

	// Allow plugins to filter an array of excluded pages (but don't put a nullstring into the array).
	$exclude_array = ( $parsed_args['exclude'] ) ? explode( ',', $parsed_args['exclude'] ) : array();

	/**
	 * Filters the array of pages to exclude from the pages list.
	 *
	 * @since 2.1.0
	 *
	 * @param string[] $exclude_array An array of page IDs to exclude.
	 */
	$parsed_args['exclude'] = implode( ',', apply_filters( 'wp_list_pages_excludes', $exclude_array ) );

	$parsed_args['hierarchical'] = 0;

	// Query pages.
	$pages = get_pages( $parsed_args );

	if ( ! empty( $pages ) ) {
		if ( $parsed_args['title_li'] ) {
			$output .= '<li class="pagenav">' . $parsed_args['title_li'] . '<ul>';
		}
		global $wp_query;
		if ( is_page() || is_attachment() || $wp_query->is_posts_page ) {
			$current_page = get_queried_object_id();
		} elseif ( is_singular() ) {
			$queried_object = get_queried_object();
			if ( is_post_type_hierarchical( $queried_object->post_type ) ) {
				$current_page = $queried_object->ID;
			}
		}

		$output .= walk_page_tree( $pages, $parsed_args['depth'], $current_page, $parsed_args );

		if ( $parsed_args['title_li'] ) {
			$output .= '</ul></li>';
		}
	}

	/**
	 * Filters the HTML output of the pages to list.
	 *
	 * @since 1.5.1
	 * @since 4.4.0 `$pages` added as arguments.
	 *
	 * @see wp_list_pages()
	 *
	 * @param string    $output      HTML output of the pages list.
	 * @param array     $parsed_args An array of page-listing arguments. See wp_list_pages()
	 *                               for information on accepted arguments.
	 * @param WP_Post[] $pages       Array of the page objects.
	 */
	$html = apply_filters( 'wp_list_pages', $output, $parsed_args, $pages );

	if ( $parsed_args['echo'] ) {
		echo $html;
	} else {
		return $html;
	}
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_list_pages’, string $output, array $parsed_args, WP_Post[] $pages )

Filters the HTML output of the pages to list.

apply_filters( ‘wp_list_pages_excludes’, string[] $exclude_array )

Filters the array of pages to exclude from the pages list.

Changelog