Loading Now

wp_list_pages WordPress: how to use it effectively

wp_list_pages WordPress

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 is true.
  • 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 or false).
  • sort_column (string) – Sorting criteria (post_title, menu_order, post_date, ID).
  • sort_order (string) – Order direction (ASC or DESC).
  • 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

Bạn có thể đã bỏ qua