This page redirects to an external site: https://developer.wordpress.org/reference/functions/wp_list_pages/
Languages: 中文(简体) • English • 日本語 (Add your language)
Displays a list of WordPress Pages as links. It is often used to customize the Sidebar or Header, but may be used in other Templates as well.
<?php wp_list_pages( $args ); ?>
<?php $args = array(
'authors' => '',
'child_of' => 0,
'date_format' => get_option('date_format'),
'depth' => 0,
'echo' => 1,
'exclude' => '',
'include' => '',
'link_after' => '',
'link_before' => '',
'post_type' => 'page',
'post_status' => 'publish',
'show_date' => '',
'sort_column' => 'menu_order, post_title',
'sort_order' => '',
'title_li' => __('Pages'),
'walker' => new Walker_Page
); ?>
By default, the usage shows:
Note: generically, arguments are inherited from get_pages.
The default heading of the list ("Pages") of Pages generated by wp_list_pages can be hidden by passing a null or empty value to the title_li parameter. The following example displays no heading text above the list.
<ul>
<?php wp_list_pages('title_li='); ?>
</ul>
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 <h2>:
<ul>
<?php wp_list_pages('include=5,9,23&title_li=<h2>' . __('Poetry') . '</h2>' ); ?>
</ul>
The following example lists the Pages in the order defined by the Order setting for each Page in the Pages→Edit panel.
<ul>
<?php wp_list_pages('sort_column=menu_order'); ?>
</ul>
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:
<ul>
<?php wp_list_pages('sort_column=menu_order&title_li=<h2>' . __('Prose') . '</h2>' ); ?>
</ul>
Using the following piece of code, the Pages will display without heading and in Page Order:
<ul>
<?php wp_list_pages('sort_column=menu_order&title_li='); ?>
</ul>
This example displays Pages sorted by (creation) date, and shows the date next to each Page list item.
<ul>
<?php wp_list_pages('sort_column=post_date&show_date=created'); ?>
</ul>
Use the exclude parameter to hide certain Pages from the list to be generated by wp_list_pages.
<ul>
<?php wp_list_pages('exclude=17,38' ); ?>
</ul>
To include only certain Pages in the list, for instance, Pages with ID numbers 35, 7, 26 and 13, use the include parameter.
<ul>
<?php wp_list_pages('include=7,13,26,35&title_li=<h2>' . __('Pages') . '</h2>' ); ?>
</ul>
Versions prior to Wordpress 2.0.1 :
Put this inside the the_post() section of the page.php template of your WordPress theme after the_content(), or put it in a copy of the page.php template that you use for pages that have sub-pages:
<ul>
<?php
global $id;
wp_list_pages("title_li=&child_of=$id&show_date=modified
&date_format=$date_format"); ?>
</ul>
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 tag (either <ul> or <ol>) even if there are no subpages. Keep this in mind if you are using css to style the list.
<ul>
<?php
wp_list_pages('title_li=&child_of='.$post->ID.'&show_date=modified
&date_format=$date_format'); ?>
</ul>
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:
<?php
$children = wp_list_pages('title_li=&child_of='.$post->ID.'&echo=0');
if ($children) { ?>
<ul>
<?php echo $children; ?>
</ul>
<?php } ?>
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.
<?php
if($post->post_parent)
$children = wp_list_pages("title_li=&child_of=".$post->post_parent."&echo=0");
else
$children = wp_list_pages("title_li=&child_of=".$post->ID."&echo=0");
if ($children) { ?>
<ul>
<?php echo $children; ?>
</ul>
<?php } ?>
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.
<?php
$output = wp_list_pages('echo=0&depth=1&title_li=<h2>Top Level Pages </h2>' );
if (is_page( )) {
$page = $post->ID;
if ($post->post_parent) {
$page = $post->post_parent;
}
$children=wp_list_pages( 'echo=0&child_of=' . $page . '&title_li=' );
if ($children) {
$output = wp_list_pages ('echo=0&child_of=' . $page . '&title_li=<h2>Child Pages</h2>');
}
}
echo $output;
?>
<?php
if($post->post_parent) {
$children = wp_list_pages("title_li=&child_of=".$post->post_parent."&echo=0");
$titlenamer = get_the_title($post->post_parent);
}
else {
$children = wp_list_pages("title_li=&child_of=".$post->ID."&echo=0");
$titlenamer = get_the_title($post->ID);
}
if ($children) { ?>
<h2> <?php echo $titlenamer; ?> </h2>
<ul>
<?php echo $children; ?>
</ul>
<?php } ?>
The following lists all top-level pages and
<?php
$ancestor_id=1843;//this code is wrong
$descendants = get_pages(array('child_of' => $ancestor_id));
$incl = "";
foreach ($descendants as $page) {
if (($page->post_parent == $ancestor_id) ||
($page->post_parent == $post->post_parent) ||
($page->post_parent == $post->ID))
{
$incl .= $page->ID . ",";
}
}?>
<ul>
<?php wp_list_pages(array("child_of" => $ancestor_id, "include" => $incl, "link_before" => "", "title_li" => "", "sort_column" => "menu_order"));?>
</ul>
This is how to get the whole subpages list
<?php
if(!$post->post_parent){
// will display the subpages of this top level page
$children = wp_list_pages("title_li=&child_of=".$post->ID."&echo=0");
}
else{
if($post->ancestors) {
// now you can get the the top ID of this page
// wp is putting the ids DESC, thats why the top level ID is the last one
$ancestors = get_post_ancestors($this_page);
$children = wp_list_pages("title_li=&child_of=".$ancestors."&echo=0");
}
}
if ($children) { ?>
<ul>
<?php echo $children; ?>
</ul>
<?php } ?>
Since there's no way to tell wp_list_pages to display a particular parent tree (parent and all generations displayes) this example uses get_pages to get all the descendants for a parent, then use wp_list_pages to display the 'family tree'.
<?php
// use wp_list_pages to display parent and all child pages all generations (a tree with parent)
$parent = 93;
$args=array(
'child_of' => $parent
);
$pages = get_pages($args);
if ($pages) {
$pageids = array();
foreach ($pages as $page) {
$pageids[]= $page->ID;
}
$args=array(
'title_li' => 'Tree of Parent Page ' . $parent,
'include' => $parent . ',' . implode(",", $pageids)
);
wp_list_pages($args);
}
?>
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'.
<?php
//if the post has a parent
if($post->post_parent){
//collect ancestor pages
$relations = get_post_ancestors($post->ID);
//get child pages
$result = $wpdb->get_results( "SELECT ID FROM wp_posts WHERE post_parent = $post->ID AND post_type='page'" );
if ($result){
foreach($result as $pageID){
array_push($relations, $pageID->ID);
}
}
//add current post to pages
array_push($relations, $post->ID);
//get comma delimited list of children and parents and self
$relations_string = implode(",",$relations);
//use include to list only the collected pages.
$sidelinks = wp_list_pages("title_li=&echo=0&include=".$relations_string);
}else{
// display only main level and children
$sidelinks = wp_list_pages("title_li=&echo=0&depth=1&child_of=".$post->ID);
}
if ($sidelinks) { ?>
<h2><?php the_title(); ?></h2>
<ul>
<?php //links in <li> tags
echo $sidelinks; ?>
</ul>
<?php } ?>
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):
if(!function_exists('get_post_top_ancestor_id')){
/**
* Gets the id of the topmost ancestor of the current page. Returns the current
* page's id if there is no parent.
*
* @uses object $post
* @return int
*/
function get_post_top_ancestor_id(){
global $post;
if($post->post_parent){
$ancestors = array_reverse(get_post_ancestors($post->ID));
return $ancestors[0];
}
return $post->ID;
}}
Next, add the following code to your theme (wherever you want the menu to appear):
<ul class="clearfix">
<?php wp_list_pages( array('title_li'=>'','include'=>get_post_top_ancestor_id()) ); ?>
<?php wp_list_pages( array('title_li'=>'','depth'=>1,'child_of'=>get_post_top_ancestor_id()) ); ?>
</ul>
If you want a link to the blog page as well use wp_page_menu().
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:
<?php
$args = array(
'post_type'=>'portfolio',
'title_li'=> __('Portfolio')
);
wp_list_pages( $args );
?>
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 the title_li parameter to an empty string.
All list items (li) generated by wp_list_pages() are marked with the class page_item. When wp_list_pages() is called while displaying a Page, the list item for that Page is given the additional class current_page_item.
<li class="pagenav">
Pages [title_li]
<ul>
<!-- Output starts here if 'title_li' parameter is empty -->
<li class="page-item-2 page_item current_page_ancestor current_page_parent">
[parent of the current Page]
<ul>
<li class="page-item-21 page_item current_page_item">
[the current Page]
</li>
</ul>
</li>
<li class="page-item-3 page_item">
[another Page]
</li>
</ul>
</li>
They can be styled with CSS selectors:
.pagenav { … } /* the outermost list item; contains whole list */
.page-item-2 { … } /* item for Page ID 2 */
.page_item { … } /* any Page item */
.current_page_item { … } /* the current Page */
.current_page_parent { … } /* parent of the current Page */
.current_page_ancestor { … } /* any ancestor of the current Page */
In order to achieve an accordion menu effect for instance, the following CSS can be used:
.pagenav ul ul,
.pagenav .current_page_item ul ul,
.pagenav .current_page_ancestor ul ul,
.pagenav .current_page_ancestor .current_page_item ul ul,
.pagenav .current_page_ancestor .current_page_ancestor ul ul {
display: none;
}
.pagenav .current_page_item ul,
.pagenav .current_page_ancestor ul,
.pagenav .current_page_ancestor .current_page_item ul,
.pagenav .current_page_ancestor .current_page_ancestor ul,
.pagenav .current_page_ancestor .current_page_ancestor .current_page_item ul,
.pagenav .current_page_ancestor .current_page_ancestor .current_page_ancestor ul {
display: block;
}
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.
link_before, link_after and exclude_tree parameters.number and offset parameters.wp_list_pages() is located in wp-includes/post-template.php.