wp_list_pages WordPress: how to use it effectively
Introduction
wp_list_pages()
is a powerful function in WordPress that allows you to generate a list of pages dynamically. It is commonly used in themes to create navigation menus or sidebar page lists. This function provides various parameters to control the output, making it highly customizable.
📌 Learn more about WordPress functions: WordPress Developer Handbook
Basic usage wp_list_pages in WordPress
To use wp_list_pages()
, simply add the following code in your theme files where you want to display the page list:
<?php wp_list_pages(); ?>
By default, this will output an unordered list (<ul>
) of all published pages.
Customizing the output
You can customize the output of wp_list_pages()
using an array of arguments or a query string format. Below are the available parameters:
Available parameters
wp_list_pages()
accepts the following arguments:
- child_of (int) – Display only subpages of a specific page ID.
- depth (int) – Determines the depth of subpages to be included. Default is 0 (all levels).
- echo (bool) – Whether to echo the output (
true
) or return it as a string (false
). Default istrue
. - exclude (string) – Comma-separated list of page IDs to exclude.
- exclude_tree (string) – Excludes a page and all its subpages.
- include (string) – Comma-separated list of page IDs to include.
- link_after (string) – Text or HTML to append to the link text.
- link_before (string) – Text or HTML to prepend to the link text.
- meta_key (string) – Retrieve pages with a specific meta key.
- meta_value (string) – Retrieve pages with a specific meta value.
- post_type (string) – Type of post to list. Default is
page
. - post_status (string) – Page status (
publish
,pending
,draft
, etc.). - show_date (bool/string) – Display page date (
created
,modified
orfalse
). - sort_column (string) – Sorting criteria (
post_title
,menu_order
,post_date
,ID
). - sort_order (string) – Order direction (
ASC
orDESC
). - title_li (string) – Title for the list. Default is
"Pages"
. - walker (object) – Custom Walker class to modify output.
More examples wp_list_pages in WordPress
1. Display pages with a custom class
You can wrap the list inside a <div>
with a custom class:
<div class="custom-page-list">
<?php wp_list_pages('title_li=<h3>Our Pages</h3>'); ?>
</div>
2. Display only top-level pages (No Child Pages)
To show only parent pages, set depth=1
:
<?php wp_list_pages('depth=1&title_li='); ?>
3. Display pages in alphabetical order
Sort pages by title in ascending order:
<?php wp_list_pages('sort_column=post_title&sort_order=ASC&title_li='); ?>
4. Display only pages with a specific status
To list only draft pages:
<?php wp_list_pages(array(
'post_status' => 'draft',
'title_li' => 'Draft Pages'
)); ?>
📌 Read more about page statuses in WordPress: WordPress Page Status
5. Exclude a parent page and its subpages
To exclude an entire page hierarchy, use exclude_tree
:
<?php wp_list_pages('exclude_tree=42&title_li='); ?>
6. Return the page list as a String (Without Echoing)
To store the list in a variable instead of directly outputting it:
<?php
$page_list = wp_list_pages(array(
'title_li' => '',
'echo' => false
));
echo '<nav>' . $page_list . '</nav>';
?>
Example: Custom page navigation
Here is an example of a custom navigation menu using wp_list_pages()
:
<div class="custom-navigation">
<h3>Site Pages</h3>
<ul>
<?php wp_list_pages('title_li='); ?>
</ul>
</div>
Conclusion
The wp_list_pages()
function is a useful tool for dynamically listing pages in WordPress. With its various parameters, you can customize the output to fit your website’s needs. If you need even more flexibility, consider using wp_nav_menu()
, which supports WordPress’s built-in menu system.
📌 Alternative function: wp_nav_menu Documentation
By leveraging wp_list_pages()
, you can create structured navigation and improve user experience effortlessly.
Read more:
Get Page IDs in WordPress: 3 Easy Methods
Share this content:
Post Comment