Template Tags/wp list pages « WordPress Codex

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

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. Default empty.
include array
Comma-separated list of page IDs to include. Default empty.
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. Default empty.
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'.

Return

void|string Void if 'echo' argument is true, HTML list of pages if 'echo' is false.

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.

.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_item
This class is added to menu items that correspond to the currently rendered static page.

.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
This class is added to menu items that correspond to a hierarchical ancestor of the currently rendered static page.

Source

wp-includes/post-template.php

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

Version	Description
4.7.0	Added the `item_spacing` argument.
1.5.0	Introduced.

Description

See also

Parameters

Return

More Information

Source

Hooks

Changelog