I'm a bit confused about wp_list_pages() function.

Lets say I have 3 top level pages (with no parent) and each of them have some sub-pages:

  • page 1 [sub-pages: 1.1, 1.2, 1.3];
  • page 2 [sub-pages: 2.1, 2.2, 2.3];
  • page 3 [sub-pages: 3.1, 3.2]

What I'm trying to do is to display top level pages 2 and 3 with all their subpages:

wp_list_pages( 'sort_column=menu_order&depth=0&title_li=&include=2,3' );

I have also tried so specify the depth as depth=2:

wp_list_pages( 'sort_column=menu_order&depth=2&title_li=&include=2,3' );

However, the top level pages 2 and 3 are displayed with no subpages. I'm not sure if I understood the function description correctly.

How do I achive such functionality when sub-pages can be added/deleted at any time.

Many thanks, Dasha

  • When you use include you're explicitly setting which pages to return in the result, so you're basically limiting the result to those two pages.
    – t31os
    Mar 23, 2011 at 11:27
  • @t31os Oh I see. Is there some smart way to do what I'm trying to achieve? Thanks.
    – dashaluna
    Mar 23, 2011 at 11:47
  • exclude_tree? eg: wp_list_pages( 'exclude_tree=N&yourotherargs=something' ) where N would be an ID of the top level page to exclude.
    – t31os
    Mar 23, 2011 at 11:50
  • @t31os thanks for the tip. I went for include option and collecting all the pages ids to be displayed.
    – dashaluna
    Mar 23, 2011 at 16:32

2 Answers 2


When you use include parameter of wp_list_pages you are basically telling it to only include these certain Pages in the list.

you should use exclude_tree instead, when using this parameter it will exclude a parent and all of that parent's child Pages.

so something like:

$top_pages_to_exclude = '1'; // the top page to be excluded ID, you can specify more then one '1,2,23'

$args = array(
    'sort_column' => 'menu_order',
    'depth' => 2,
    'title_li' => '',
    'exclude_tree' => $top_pages_to_exclude
wp_list_pages( $args );
  • thanks a lot for that! It pointed me in the right direction. It's very important to be able to create new top level pages, for example for the [wordpress.org/extend/plugins/improved-include-page] (Improved Include Page Plugin). In the case of exclude_tree I would need to update it every time a new top level page is added. So I went for a bit different solution: go through all the menu pages and collect their descendants. Please see my answer for code.
    – dashaluna
    Mar 23, 2011 at 16:20

Thanks to @Bainternet for pointing me to the exclude_tree, although I ended up using a bit different code.

It was important to be able to add top-level pages that don't have to appear in the menu (for example for Improved Include Page Plugin. Using the exclude_tree I would need to update the code every time a new top-level page is added.

Instead, I have an array of all top-level pages that need to appear in the menu. I then collect all their desendant pages and use wp_list_pages to display only secelted pages.

Here is the code:

<?php //main nav: use wp_list_pages to display cirtain parents pages and all thier descendant pages
$parents = array(2,3);
$children = array();
foreach($parents as $parent) {
    $child_pages = get_pages( "child_of=$parent" );
        foreach($child_pages as $child_page){
            $children[] = $child_page->ID;
//merge $parents and $children
$menu_pages = array_merge((array)$parents, (array)$children);
$menu_pages_str = implode(",", $menu_pages); 

<ul id="main-nav">
    <?php wp_list_pages( "sort_column=menu_order&title_li=&include=$menu_pages_str" ); ?>

Also, have a look at the Codex List parent Page and all descendant Pages for more examples.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.