wp_list_pages( array|string $args = '' )
Retrieve or display a list of pages (or hierarchical post type items) in list (li) format.
Contents
Description Description
See also See also
Parameters Parameters
- $args
-
(array|string) (Optional) 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 (Walker_Page).
Default value: ''
- 'child_of'
Return Return
(void|string) Void if 'echo' argument is true, HTML list of pages if 'echo' is false.
More Information More Information
Menu Item CSS Classes 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 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 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 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 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 Source
File: 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; } }
Expand full source code Collapse full source code View on Trac
Changelog Changelog
Version | Description |
---|---|
4.7.0 | Added the item_spacing argument. |
1.5.0 | Introduced. |
User Contributed Notes User Contributed Notes
You must log in before being able to contribute a note or feedback.
List Sub-Pages
Versions prior to WordPress 2.0.1:
Put this inside the
the_post()
section of thepage.php
template of your WordPress theme afterthe_content()
, or put it in a copy of the page.php template that you use for pages that have sub-pages:This example does not work with WordPress 2.0.1 or newer if placed in a page template because the global
$id
is not set. Use the following code instead.WordPress 2.0.1 or newer:
NOTE: Requires an HTML list tag (either
<ul>
or<ol>
) even if there are no subpages. Keep this in mind if you are using CSS to style the list.The following example will generate a list only if there are child pages (pages that designate the current page as a parent) for the current page:
Hiding or Changing the List Heading
The default heading of the list (“Pages”) of Pages generated by
wp_list_pages
can be hidden by passing a null or empty value for thetitle_li
parameter. The following example displays no heading text above the list.In the following example, only Pages with IDs 9, 5, and 23 are included in the list and the heading text has been changed to the word “Poetry”, with a heading style of :
List members of a custom post type
If a given custom post type is hierarchical in nature, then
wp_list_pages()
can be used to list the member of that custom post type. In this example the custom post type Portfolio is listed:I didn’t see anywhere that you could pass a sort_order argument. So I think it would be good to make it more obvious by including it in the args list.
This code orders pages by post_date and sorts the pages by descending order so that you will get the latest pages first.
List subpages even if on a subpage
The above examples will only show the children from the parent page, but not when actually on a child page. This code will show the child pages, and only the child pages, when on a parent or on one of the children.
This code will not work if placed after a widget block in the sidebar.
Expand full source codeCollapse full source code
As an alternative, this code in a
sidebar.php
, displays only top level pages, but when viewing a page that has children (or is a child) it displays only children of that parent.When visiting main page, all top level pages are listed in the sidebar.
When visiting a top level page with no children, all top level pages are listed.
When visiting a top level page with children, just the children pages, and descendant pages, are listed.
When visiting a child page, just the children, and descendant pages, of that parent, are listed.
Expand full source codeCollapse full source code
Page list that only displays if child (sub) pages exist, displays page list of subpages on the parent page AND on the child pages
However this code keeps the parent page name in the title which makes it different from the previous example.
Expand full source codeCollapse full source code
Markup and styling of page items
By default,
wp_list_pages()
generates a nested, unordered list of WordPress pages created with the Write > Page admin panel. You can remove the outermost item (li.pagenav
) and list (ul
) by setting thetitle_li
parameter to an empty string.All list items (
li
) generated bywp_list_pages()
are marked with the classpage_item
. Whenwp_list_pages()
is called while displaying a page, the list item for that Page is given the additional classcurrent_page_item
.Expand full source codeCollapse full source code
They can be styled with CSS selectors:
Expand full source codeCollapse full source code
Exclude Pages from List
Use the
exclude
parameter to hide certain pages from the list to be generated bywp_list_pages
.*Custom Post/Page Types*
Custom page types will require the hierarchical property to be set to true in the register_post_type (see https://developer.wordpress.org/reference/functions/register_post_type/) parameter list.
By default the only WordPress post type that is hierarchical is the ‘page’ type.
Only hierarchical post types are returned by this function.
List Pages by Page Order
The following example lists the pages in the order defined by the
Order
setting for each page in the Pages→Edit panel.If you wanted to sort the list by page order and display the word “Prose” as the list heading (in h2 style) on a sidebar, you could add the following code to the sidebar.php file:
Using the following piece of code, the pages will display without heading and in page order:
Sort Pages by Post Date
This example displays Pages sorted by (creation) date, and shows the date next to each page list item.
Include Pages in List
To include only certain pages in the list, for instance, pages with ID numbers 35, 7, 26 and 13, use the
include
parameter.List all top-level pages and subpages only of this parent
The following lists all top-level pages and
if on a top level page – children of only this page
if on a subpage – its siblings but not children of other top pages
Expand full source codeCollapse full source code
List whole subpages
This is how to get the whole subpages list
Expand full source codeCollapse full source code
List parent page and all descendant pages
Since there’s no way to tell
wp_list_pages
to display a particular parent tree (parent and all generations displayes) this example usesget_pages
to get all the descendants for a parent, then usewp_list_pages
to display the ‘family tree’.Expand full source codeCollapse full source code
List current Page with its ancestors and children
This example will list current page, ancestors of current page, and children of current page, Since
child_of
displays all children,wpdb
is used instead, along with include to not display everything ‘and the kitchen sink’.Expand full source codeCollapse full source code
List topmost ancestor and its immediate children
This method will show the topmost ancestor of the current page as well as the topmost ancestor’s immediate children. This can be used for clean secondary subnavigation.
First, create the following function (preferably in
functions.php
, assuming this is for a theme):Expand full source codeCollapse full source code
Next, add the following code to your theme (wherever you want the menu to appear):
Expand full source codeCollapse full source code
List the Home page
If you want a link to the blog page as well use
wp_page_menu()
.