Using wp_list_pages
This post describes the basics of working with wp_list_pages.
wp_list_pages overview
The wp_list_pages function generates a list of links to pages in your WordPress site. The list is generated as an li tag with a title and a nested ul containing a list of links. For example, if your site had pages named About and Contact wp_list_pages() would generate:
Pages
Styling the page list heading
By default the wp_list_pages displays “Pages” within the li tag. You change the label and or add a tag to it by using the title_li option. For example the following prints Pages as an h3.
<?php wp_list_pages('title_li=<h3>Pages</h3>'); ?>
Or display no title at all:
<?php wp_list_pages('title_li='); ?>
Note! In this case the outer li and ul are removed. For example if your pages were About and Contact you would have:
About
Contact
Styling the page list
Each of the li tags generated by wp_list_pages is assigned the following class names:
- page_item
- page-item-id – Where id is the id number of the page
The class page_item is very useful. Note that it uses the _ rather than the -.
The class page-item-id on the other is less useful. WordPress generates an id number for each page. This number is a little unpredictable. Id numbers really have no rhyme or reason.
When a page is currently displayed the link that matches the page will also have the class:
- current_page_item
This is a very useful property that can be used to assign a style to the current page link.
Sample Selectors
The first step to creating a style for the page links is to define a selector that will target the links. Since all links will end up in li tag within the container element the descendant selector works well. For this example imagine the pages links are contained within an element with the id name nav
#nav li {...styles...}
To be more specific and target only the page links rather than all of the list items, the class page_item is assigned to all page links.
#nav .page_item {...styles...}
To style the selected page differently from the other pages links, use the class current_page_item.
#nav .current_page_item {...styles...}
To target the anchor tag within each of the list items generated by wp_list_pages, use the descendant or child selectors any of the following should work.
#nav li a{...styles...}
#nav .page_item a{...styles...}
#nav .current_page_item a{...styles...}
Sample Styles
Here’s a few ideas on styling the page links. Be sure to use the :link, :visited, :hover and :active styles.
#nav li a:link{...styles...}
#nav li a:visited{...styles...}
#nav li a:hover{...styles...}
#nav li a:active{...styles...}
Be sure to style the current_page_item after the other links styles.
Here’s a few more ideas. Make every link appear as a box. Set each anchor tag to display block:
.page_item a { display:block; }
Make a horizontal list of links with float. Floating the list may require that you clear the floated elements later in your page.
.page_item a {
display:block;
float:left;
}
Adding padding on all sides to expand the link boxes. Here’s an idea use the border-radius property to add rounded corners. You could easily create some tabs by rounding only the top corners.
Other options
The wp_list_pages method provides many options. For a full list of options see the WordPress Codex.
Here are a few possibilities. Since pages can be nested, use the depth option to set the number of levels of pages that will be displayed. For example depth=1 displays only the top level pages.
Use the & between properties. For example, the line below creates a list of pages with no title and a depth of 1.