WordPress get_pages Function [Full Guide]

WordPress get_pages function

What is the get_pages() function used for?

WordPress, the driving force behind countless websites, provides a wide range of features to effectively handle and modify content. One of these notable features is the get_pages() function, which serves as a flexible tool for retrieving and showcasing pages within WordPress. In this all-encompassing guide, we will thoroughly examine the intricacies of get_pages(), delving into its syntax, parameters, and practical uses. By doing so, developers will be equipped with the knowledge to fully utilize the immense capabilities of get_pages() in WordPress development.

Description of get_pages() Parameters

Basic syntax:


get_pages( $args )



Array or string of arguments to retrieve pages.

  • child_of (int) – Page ID to return child and grandchild pages of. Note: The value of $hierarchical has no bearing on whether $child_of returns hierarchical results. Default 0, or no restriction.
  • sort_order (string). How to sort retrieved pages. Accepts 'ASC''DESC'. Default 'ASC'.
  • sort_column (string). What columns to sort pages by, comma-separated. Accepts 'post_author''post_date''post_title''post_name''post_modified''menu_order''post_modified_gmt''post_parent''ID''rand''comment*count'.
    'post*' can be omitted for any values that start with it.
    Default 'post_title'.
  • hierarchical (bool). Whether to return pages hierarchically. If false in conjunction with $child_of also being false, both arguments will be disregarded.
    Default true.
  • exclude (int[]). Array of page IDs to exclude.
  • include (int[]). Array of page IDs to include. Cannot be used with $child_of$parent$exclude$meta_key$meta_value, or $hierarchical.
  • meta_key (string). Only include pages with this meta key.
  • meta_value (string). Only include pages with this meta value. Requires $meta_key.
  • authors (string). A comma-separated list of author IDs.
  • parent (int). Page ID to return direct children of. Default -1, or no restriction.
  • exclude_tree (string|int[]). Comma-separated string or array of page IDs to exclude.
  • number (int). The number of pages to return. Default 0, or all pages.
  • offset (int). The number of pages to skip before returning. Requires $number.
    Default 0.
  • post_type (string). The post type to query. Default 'page'.
  • post_status (string|array). A comma-separated list or array of post statuses to include.
    Default 'publish'.


WP_Post[] | false – Array of pages (or hierarchical post type items). Boolean false if the specified post type is not hierarchical or the specified status is not supported by the post type.

How to use get_pages() in WordPress

Let’s explore some practical applications of get_pages():

1. Displaying a List of Pages:


$pages = get_pages();
foreach ( $pages as $page ) {
    echo '<a href="' . get_page_link( $page->ID ) . '">' . $page->post_title . '</a><br>';

This example retrieves all pages and generates HTML links for each page’s title, providing a basic list of pages that can be used for navigation or other purposes.

2. Show pages with specified template:


$pages = get_pages( array( 
    'meta_key'     => '_wp_page_template', 
    'meta_value'   => 'page-tpl.php', 
    'hierarchical' => 0

foreach( $pages as $page ){
    echo "$page->post_title <br>";

In this example we’re fetching all the page with the “page-tpl.php” template.


The get_pages() function in WordPress empowers developers with a powerful tool for retrieving and manipulating page data within WordPress. By understanding its syntax, parameters, and practical applications, developers can leverage get_pages() to build dynamic navigation menus, create custom page templates, and implement advanced page-related functionalities in WordPress themes and plugins. Whether it’s generating page listings, customizing page queries, or creating custom page templates, get_pages() offers unparalleled flexibility and control, enabling developers to craft immersive and engaging user experiences within the WordPress ecosystem.

About The Author

Andriy Haydash

Andriy Haydash

Andriy Haydash is a WordPress Expert who helps people build and launch successful WordPress membership and e-learning websites.

Note: Not all of the articles are written directly by me.
Affiliate Disclaimer: Some links in the post may be my affiliate links

The Ultimate Managed Hosting Platform

Before YOU Leave...
Join My Newsletter

Get practical tips & tricks on how to start, grow and market your course/membership site.