Getting the Most Out of Your WordPress Template Tags: Listing Pages


Getting the Most Out of Your WordPress Template Tags (LOGO)

This series on Getting the Most Out of Your WordPress Template Tags is meant to help you speed up and, even more so, improve your use of WordPress Template Tags.

The following tag is suggested (and provided) for use in WordPress blogs in order to generate a list of the pages of a blog:

<?php wp_list_pages(); ?>

Of course it is possible to manually list and link each page of your blog. But this is not ideal. Today we look at the wp_list_pages tag.

The Basics

There are a number of ways that I’m used to seeing wp_list_pages used. Now just because we’re used to seeing them doesn’t mean they are the best ways. Let’s take a look at how it could be, what the result turns out to be, and then look to what we want to begin doing.

The (Usually) Standard

<?php wp_list_pages('title_li='); ?>

The above code produces a very simple list without any header. Without title_li= in the parenthesis the list would print with an <h2> that says Pages. Since we are looking to use this tag for our main menu, we don’t want any header. So this is the most basic way to begin, and it will return the following:

List Pages Tutorial Step 1

Note: The tag must be wrapped in <ul> </ul> in order to validate. The function does not generate the wrapping <ul> tags.

The Exclude / Include Argument

<?php wp_list_pages('title_li=&include=1,2,4'); ?>

In some cases we run across themes which do not handle many pages in the main menu. One way of managing this issue is to drop include= into the template tag. In the example above, only pages with the IDs 1, 2 and 4 will be included in the main menu. All others will still exist, but they won’t be listed.

Another way of dealing with having too many pages to fit into your theme’s main menu area is to use the exclude argument. This performs the opposite function of the include argument. Whatever post IDs you list will be excluded from the list.

<?php wp_list_pages('title_li=&exclude=1,2,4'); ?>

In the above example pages 1, 2 and 4 would not be included in the list of pages.

Note: The ampersand (&) must be used in between arguments in a template tag.

Little-Used Arguments

The three arguments listed above (title_li, include, exclude) are fairly basic. Let’s look at some stuff that isn’t used often, and see what sort of things there are to gain from them.

List Depth

Use this one for dealing with Subpages. Let’s say you have a theme that doesn’t support Subpages in a menu very well. Take UrbanGrunge, for example, a recent addition to the WordPress Theme Viewer. In the screenshot below you can see that our Subpages don’t look great when they’re used in the UrbanGrunge theme.

List Pages Tutorial Step 2

As you can see, the theme pushes our Subpage down a level. It looks odd, not to mention the fact that it makes our last few menu items unreadable. This author didn’t prepare the theme for Subpage. Let’s fix it.

The current code:

<?php wp_list_pages('title_li='); ?>

With our addition:

<?php wp_list_pages('title_li=&depth=1'); ?>

Our addition, depth=1, tells the tag to only generate the first level of menu items. All subpages are ignored.

List PAges Tutorial Step 3

This fixes the major problems in our menu. With a little more tweaking (probably by excluding a page or two) this menu would look great!

List Order

I use this one constantly. For anyone who has ever wanted to list their menu in a very specific manner (a good thing to do) this argument is made for just that. While there are a number of options for this argument, the one most useful to us is menu_order.

<?php wp_list_pages ('title_li= &list_column=menu_order'); ?>

This sets the menu order to line up with the order of the pages that you determine. How do you determine the order yourself, you ask? You enter them on the Dashboard under Write / Edit Page:

List PAges Tutorial Step 4 Small

The pages will order from lowest to highest: 1, 2, 3, 4, etc.

Suggestions for Developers

I would suggest a default setting of the following:

<?php wp_list_pages('title_li=&depth=1&sort_column=menu_order'); ?>

This meets a large number of users’ default needs. Most user don’t use headings for their page listings, and most would prefer to order their page items a certain way themselves. Cutting down the depth to 1 just lowers the possibility of a user being disappointed with your theme as soon as they activate it.


11 thoughts on “Getting the Most Out of Your WordPress Template Tags: Listing Pages

  1. That’s why I liked hand-coding my pages list instead of relying on the template tag.

    One important aspect I’ve found that need to be included(perhaps there’s an attribute out there like this) is to limit the number of pages that get displayed. Many times people just have a lot of pages and when using my themes, I’ve remarked that looks weird then. Sometimes the header and description are pushed aside or things get really bad.

    Great post and great blog. I really love playing around with WordPress and themes and I think I’ve met a blog that I really like today. Hope you won’t mind my comments a bit around everywhere. When reading on such subject like this, I just don’t feel leaving without saying something.

  2. Thanks for the kind words! I love it when people find this blog useful; means there are others out there like me 🙂

    I would encourage you to check out Page Link Manager (
    wordpress-plugin-review-page-link-manager) it’s a plugin I use on _every_ site I design. It’s simply awesome, and I think it might take care of the frustration you’re talking about when it comes to too many pages. I understand completely.

    I look forward to your comments! Please, I want to hear them 🙂

  3. Pingback:   Things you should know when displaying pages in Wordpress — BlogoSquare

  4. Hi, really excellent blog – thanks.
    I’m having the same problem but with ordering of categories rather than pages. Since you can’t edit the page order for categories, changing:


    …it has no effect.

    Any suggestions for how you could manipulate gategory order (it defaults to alphabetical)?


  5. Hi,
    Really hope you can help me. I want to know if I can alter the markup that the list_pages outputs to include a SPAN tag inside the ANCHOR for each item in the list.

    This is because I want to use image replacement on the ANCHORS and then hide the HTML text in the SPANS offscreen for accessibility.

    Is there anyway to do this without resorting to handcoding the markup and removing the list_pages function altogether?

    Many thanks for your help….

  6. What a life saver! Up all night trying to get this to work through dashboard, and you make it all so simple. Thanks a million!!!

  7. Thank you very much! Thanks of this post I could solve my problem to edit my menu within the header, so that no more subpages will show up there! 🙂

Comments are closed.