How to Display a List of Child Pages for a Parent Page in WordPress
Organizing large websites in a logical, user-friendly way is crucial for both visitors and search engines. When working with a hierarchical structure, it’s often helpful to show a dynamic list of subpages that belong to the current section. In a content management system like WordPress, that means displaying a list of child pages for a specific parent page so users can easily navigate deeper into your site’s content.
Table of contents
Why Display Child Pages in WordPress?
Before diving into code, it’s useful to understand when and why you would show a list of child pages on your site:
- Improved navigation: Child pages act like subsections of a main topic, making it easier for visitors to find related content without hunting through menus.
- Better content hierarchy: Highlighting subpages under a main section reinforces the structure of your site, especially on documentation, service, or course-based websites.
- SEO benefits: Internal links from a parent page to its children help search engines understand the relationship between your pages and can strengthen topical relevance.
- Consistent user experience: When every section page automatically shows its subpages, users quickly understand how your site is organized.
WordPress has everything you need to work with a hierarchy of pages. You can create parent and child pages in the editor and then use template tags or shortcodes to output a list anywhere you like.
Understanding Parent and Child Pages
Pages in WordPress can be arranged hierarchically:
- Parent page: A top-level page that acts as a main section or category of content.
- Child page: A subpage assigned to a parent. This is configured in the Page Attributes panel while editing a page.
This hierarchy is especially common on business, documentation, and educational sites. For example, a company might have a main “Services” page with multiple child pages like “Web Development,” “SEO Consulting,” and “Maintenance Plans.” Displaying those subpages directly on the parent allows visitors to see everything available at a glance.
Method 1: Display Child Pages with wp_list_pages()
The most common approach is to modify a theme template and use the built-in wp_list_pages() function. This function outputs an HTML list of pages based on the criteria you provide.
Basic usage on a specific parent page template
If you have a dedicated template for a section (for example, page-services.php), you can add a list of subpages that belong to that section:
<?php
// Get the ID of the current page
$parent_id = get_the_ID();
// Retrieve child pages of this parent
$child_pages = wp_list_pages( array(
'title_li' => '',
'child_of' => $parent_id,
'sort_column' => 'menu_order,post_title',
'echo' => 0,
) );
// Output the list if there are any child pages
if ( $child_pages ) : ?>
<h2>Related Pages</h2>
<ul>
<?php echo $child_pages; ?>
</ul>
<?php endif; ?>
This code will:
- Detect the current page ID.
- Fetch all published child pages of that parent, ordered by menu order and then title.
- Output them inside an unordered list.
Show children for either the parent or a child
Often, you want the same list of pages to show whether a visitor is on the main section page or on any of its subpages. A common pattern is to detect the “top-level ancestor” and then list its subpages.
<?php
global $post;
// Determine the parent (top ancestor) ID
if ( $post->post_parent ) {
$ancestor_ids = array_reverse( get_post_ancestors( $post->ID ) );
$top_parent_id = $ancestor_ids[0];
} else {
$top_parent_id = $post->ID;
}
// Get children of the top-level ancestor
$child_pages = wp_list_pages( array(
'title_li' => '',
'child_of' => $top_parent_id,
'sort_column' => 'menu_order,post_title',
'echo' => 0,
) );
// Only display if there are children
if ( $child_pages ) : ?>
<aside>
<h2>Section Pages</h2>
<ul>
<?php echo $child_pages; ?>
</ul>
</aside>
<?php endif; ?>
This works well in a sidebar or in a block-based template part where you want to show a contextual navigation menu for a section.
Method 2: Use get_children() for More Control
While wp_list_pages() is simple, it has limited flexibility for customizing the output. If you want more control over HTML markup, excerpts, featured images, or custom fields, use get_children() or a direct WP_Query instead.
Example using get_children()
<?php
$parent_id = get_the_ID();
$children = get_children( array(
'post_parent' => $parent_id,
'post_type' => 'page',
'orderby' => 'menu_order',
'order' => 'ASC',
) );
if ( ! empty( $children ) ) : ?>
<section>
<h2>Subpages in This Section</h2>
<ul>
<?php foreach ( $children as $child ) : ?>
<li>
<a href="<?php echo get_permalink( $child->ID ); ?>">
<?php echo esc_html( get_the_title( $child->ID ) ); ?>
</a>
</li>
<?php endforeach; ?>
<ul>
</section>
<?php endif; ?>
Because you have access to each post object, you can extend this markup to include additional information.
Include excerpts or custom content
<?php foreach ( $children as $child ) : ?>
<article>
<h3>
<a href="<?php echo get_permalink( $child->ID ); ?>">
<?php echo esc_html( get_the_title( $child->ID ) ); ?>
</a>
</h3>
<p>
<?php echo esc_html( wp_trim_words( $child->post_content, 25, '...' ) ); ?>
</p>
</article>
<?php endforeach; ?>
This kind of layout is ideal for hub pages that introduce each subtopic with a short description and link through to the full page.
Method 3: Query Child Pages Using WP_Query
Using WP_Query gives you full access to the loop API and lets you apply conditions, pagination, and more advanced filtering when working with child pages.
Basic WP_Query example for child pages
<?php
$parent_id = get_the_ID();
$child_query = new WP_Query( array(
'post_type' => 'page',
'post_parent' => $parent_id,
'posts_per_page' => -1,
'orderby' => 'menu_order',
'order' => 'ASC',
) );
if ( $child_query->have_posts() ) : ?>
<section>
<h2>Pages in This Section</h2>
<ul>
<?php while ( $child_query->have_posts() ) : $child_query->the_post(); ?>
<li>
<a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
</li>
<?php endwhile; ?>
</ul>
</section>
<?php wp_reset_postdata(); ?>
<?php endif; ?>
This pattern is particularly useful if you want to:
- Apply additional meta queries (for example, only show pages with a certain custom field set).
- Add pagination to very long lists of child pages.
- Mix child pages with other content types in a customized query.
Creating a Reusable Shortcode for Child Pages
Editing theme templates is not always desirable, especially on sites managed by non-technical editors. A shortcode makes it possible to output a list of child pages directly within the block editor without touching PHP templates each time.
Shortcode that lists children of the current page
Add the following code to your theme’s functions.php or a small custom plugin:
function wpdev_child_pages_shortcode( $atts ) {
global $post;
$atts = shortcode_atts( array(
'parent' => $post ? $post->ID : 0,
'title' => 'Related Pages',
), $atts, 'child_pages' );
if ( ! $atts['parent'] ) {
return '';
}
$child_pages = wp_list_pages( array(
'title_li' => '',
'child_of' => (int) $atts['parent'],
'echo' => 0,
) );
if ( ! $child_pages ) {
return '';
}
$output = '<section>';
$output .= '<h2>' . esc_html( $atts['title'] ) . '</h2>';
$output .= '<ul>' . $child_pages . '</ul>';
$output .= '</section>';
return $output;
}
add_shortcode( 'child_pages', 'wpdev_child_pages_shortcode' );
Usage examples inside the editor:
[child_pages]– lists child pages of the current page.[child_pages parent="42" title="More in This Section"]– lists children of the page with ID 42 and custom heading text.
Because the shortcode simply wraps existing core functions, it remains efficient and compatible with most themes.
Integrating Child Page Lists into Block Themes
With block themes and the Site Editor, it’s common to manage layouts without editing PHP files. However, dynamic lists of child pages are still best generated with PHP. You can combine the two approaches by adding a template part in your theme that outputs the child pages, then include that template part wherever needed.
Example: Template part for section navigation
Create a file such as template-parts/section-navigation.php:
<?php
global $post;
if ( ! $post ) {
return;
}
if ( $post->post_parent ) {
$ancestor_ids = array_reverse( get_post_ancestors( $post->ID ) );
$top_parent_id = $ancestor_ids[0];
} else {
$top_parent_id = $post->ID;
}
$child_pages = wp_list_pages( array(
'title_li' => '',
'child_of' => $top_parent_id,
'echo' => 0,
) );
if ( ! $child_pages ) {
return;
}
?>
<nav aria-label="Section navigation">
<h2>Section Navigation</h2>
<ul>
<?php echo $child_pages; ?>
</ul>
</nav>
Then load this template part from your main page template (or a custom block-based PHP template) using:
<?php get_template_part( 'template-parts/section-navigation' ); ?>
This keeps your logic centralized while still letting you position the child page navigation within a modern, block-based layout.
Best Practices for Displaying Child Pages
Once your list of child pages is in place, refine the implementation for usability and performance.
1. Keep lists focused and readable
- Avoid overwhelming users with very long lists; break content into logical sub-sections.
- Consider grouping or paginating if you have dozens of child pages under a single parent.
- Use concise, descriptive page titles so the list is scannable.
2. Use meaningful headings and landmarks
- Wrap the list in semantic elements such as
<section>or<nav>. - Provide descriptive headings like “Section Pages,” “On This Topic,” or “More Resources.”
- Add ARIA labels on navigation elements for accessibility when appropriate.
3. Maintain a consistent hierarchy
- Make sure your page tree in the admin accurately reflects how you want content grouped.
- Use the “Parent” dropdown when creating or editing pages to assign them to the correct section.
- Use menu order to control the display order instead of relying solely on alphabetical titles.
4. Consider styling and design
- Add CSS rules in your theme to style the child page list in a way that matches your branding.
- Turn child pages into cards or grid layouts when you need a more visual presentation.
- Highlight the current page in the list to orient visitors within the section.
5. Pay attention to performance
- On extremely large sites, limit the depth and number of pages returned in each list.
- Cache output using transients if child page lists appear on high-traffic pages.
- Where possible, reuse template parts instead of duplicating logic across multiple files.
SEO Considerations When Linking to Child Pages
Displaying child pages is not only about usability; it also directly impacts internal linking strategy.
- Reinforce topical clusters: When a main topic page links to detailed subpages, search engines can better interpret your site as a structured content hub.
- Distribute authority: Internal links from high-authority parent pages help child pages rank better for specific, long-tail queries.
- Optimize anchor text: Page titles should be descriptive and keyword-rich without being spammy; those titles become the anchor text in your child page list.
- Encourage crawl depth: Explicit links from parent pages reduce the number of clicks it takes for crawlers (and users) to reach deeper content.
By treating your section pages as hubs that clearly expose all relevant subpages, you effectively create a semantic structure that benefits both visitors and search engines.
Conclusion
Displaying a list of child pages is an effective way to highlight your site’s structure, improve navigation, and support a stronger internal linking strategy. Whether you use theme template tags like wp_list_pages(), more flexible options like get_children() and WP_Query, or an editor-friendly shortcode, the key is to integrate these lists consistently across your important parent pages.
Start with a simple implementation, verify that the page hierarchy in the admin matches your desired structure, and then iterate on the presentation and SEO aspects. Once in place, dynamic child page lists will keep your content organized as your site grows and provide a clear, intuitive path for both users and search engines to explore your pages.
