WordPress Development Stack Exchange is a question and answer site for WordPress developers and administrators. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

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

share|improve this question
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 '11 at 11:27
@t31os Oh I see. Is there some smart way to do what I'm trying to achieve? Thanks. – dashaluna Mar 23 '11 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 '11 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 '11 at 16:32

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 );
share|improve this answer
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 '11 at 16:20
up vote 1 down vote accepted

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.

share|improve this answer

Your Answer


By posting your answer, you agree to the privacy policy and terms of service.

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