wp_list_pages() WordPress Function
The wp_list_pages() function is a built-in function in WordPress that displays a list of pages on your site. This function can be used in your WordPress theme template files to display a list of pages in your site's navigation menus. The wp_list_pages() function can be customized with a number of arguments, such as the number of pages to display, the order in which to display them, and whether to display page titles and descriptions.
wp_list_pages( array|string $args = '' ) #
Retrieves or displays a list of pages (or hierarchical post type items) in list (li) format.
Contents
Description
See also
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 which results in a Walker_Page instance being used.
Default value: ''
- 'child_of'
Return
(void|string) Void if 'echo' argument is true, HTML list of pages if 'echo' is false.
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
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 codeCollapse full source codeView on TracView on GitHub
Changelog
Version | Description |
---|---|
4.7.0 | Added the item_spacing argument. |
1.5.0 | Introduced. |