Listing Child Pages With Wp_List_Pages In Wordpress Shortcodes

The Problem: Displaying a Page’s Child Pages

A common need when building a WordPress site is to display the child pages of a specific parent page. For example, you may have a “Services” page, and want to show links to subpages like “Web Design,” “SEO,” and “Software Development.” Or an “Our Team” page with child pages for each employee. Without some development work, WordPress does not provide an automatic way to output a list of child pages.

Use cases where listing child pages is helpful include:

Displaying a table of contents for a section of a site
Showing a hierarchy within a certain topic or category
Helping users navigate to related subpages
Segmenting long content into multiple pages

Manually inserting hyperlinks to each child page is tedious. Instead, developers often leverage WordPress templates and functions to dynamically query child pages and display the list. The wp_list_pages function enables this behavior in a flexible way.

Table of Contents

Using wp_list_pages to List Child Pages

The wp_list_pages function is a built-in WordPress template tag that outputs an HTML list of pages based on specified criteria. By default, it will display all top-level site pages, but its parameters can restrict the list to child pages of a certain parent.

The key parameter for listing child pages is “child_of,” which filters the list to only pages that are children of that page’s ID. For example, if our “Services” page ID is 50:

<?php 
  wp_list_pages( array(
    'child_of' => 50
  ));  
?>

This would output a UL list of links to just the child pages of the Services page. The wp_list_pages function handles querying those pages from the WordPress database automatically.

Crafting the wp_list_pages Shortcode

In addition to using wp_list_pages directly in theme template files, it can be helpful to wrap it in a WordPress shortcode. This creates a reusable component that content editors can easily insert on pages via the shortcode [[ ]] syntax.

Here is an example wp_list_pages shortcode definition for listing child pages:

<?php
function child_pages_list( $atts ) {
    return wp_list_pages( array(
        'child_of' => $atts['parent'],
        'depth' => 1,
        'title_li' => '' 
    ));
}
add_shortcode( 'childpages', 'child_pages_list' );  
?>

This shortcode accepts a ‘parent’ attribute to specify the parent page. It limits the depth to one level to only get direct children. And it removes the title redundancy by clearing the title_li parameter.

The shortcode can then be used like:
[[childpages parent=”50″]]

Displaying the Child Page List

To display a list of child pages on the front-end, the wp_list_pages shortcode first needs to be called in one of the theme’s template files. Common options include:

In page.php to show child pages on individual pages
In page-templates/custom.php for a page-specific template
In header.php or footer.php to load globally

For example, to output the child page list above a page’s content, page.php could include:

<?php
  // Get ID of current page 
  $post_id = get_the_ID(); 
  
  // Output child page list above content
  if(!is_front_page()) {
    echo do_shortcode('[childpages parent="'. $post_id .'"]');
  } 
?>
 
<div class="content">
  <!-- Page content here -->
</div>

Styling and placement will depend on the site’s design. Displaying the list in a sidebar, footer menu, or collapsible toggle are common approaches to optimize the layout.

Customizing the List Display

There are many options for customizing the output of wp_list_pages for more advanced child page listings:

CSS classes can style the list HTML
Filters like wp_list_pages_exclude adjust items
Fields in the $args array like ‘link_before’ affect formatting
Excerpts can display under page titles

For example, to emphasize the current page in the child page list, we could write:

<?php
wp_list_pages(array(
    'child_of' => $post_id,
    'current_page' => true  
)); ?>

Which wraps the current page in SPAN tags we can target with CSS. Creative use of these parameters enables optimal presentation.

Summary

In summary, listing out child pages is a common requirement in WordPress themes. The wp_list_pages template tag provides flexible options to query and display child page links automatically. Wrapping it in a reusable shortcode simplifies insertion for non-developers. And custom params give extensive control over the rendered output.

Use cases are limitless, like navigation menus, page hierarchies, table of content lists, and more. Both users and site administrators will appreciate these kept-up-to-date navigation aides auto-generated by the wp_list_pages function in WordPress.

Listing Child Pages With Wp_List_Pages In WordPress Shortcodes