WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/wp page menu

Contents

Description

Displays a list of WordPress Pages as links, and affords the opportunity to have Home added automatically to the list of Pages displayed. This Tag is useful to customize the Sidebar or Header, but may be used in other Templates as well.

Usage

 <?php wp_page_menu$args ); ?> 

Default Usage

<?php $args = array(
        'depth'       => 0,
	'sort_column' => 'menu_order, post_title',
	'menu_class'  => 'menu',
	'include'     => '',
	'exclude'     => '',
	'echo'        => true,
	'show_home'   => false,
	'link_before' => '',
	'link_after'  => '' );
?>

By default, the usage shows:

  • All Pages and sub-pages are displayed (no depth restriction)
  • Sorted by menu order and title
  • The div class is 'menu'
  • No pages are excluded
  • No pages are explicitly included
  • Results are echoed (displayed)
  • No link_before or link_after text
  • Do not add "Home" to the list of pages
  • Note: Output is encompassed by the <ul> and </ul> tags

Parameters

depth 
(integer) This parameter controls how many levels in the hierarchy of pages are to be included in the list generated by wp_list_pages. The default value is 0 (display all pages, including all sub-pages).
  • 0 (default) Displays pages at any depth and arranges them hierarchically in nested lists
  • -1 Displays pages at any depth and arranges them in a single, flat list
  • 1 Displays top-level Pages only
  • 2, 3 … Displays Pages to the given depth
sort_column 
(string) Sorts the list of Pages in alphabetic order by title of the pages. The default setting is sort by menu order and alphabetically by page title. The sort_column parameter can be used to sort the list of Pages by the descriptor of any field in the wp_post table of the WordPress database. Some useful examples are listed here.
  • 'post_title' - Sort Pages alphabetically by title.
  • 'menu_order' - Sort Pages by Page Order. Note the difference between Page Order and Page ID. The Page ID is a unique number assigned by WordPress to every post or page. The Page Order can be set by the user in the administrative panel (e.g. Administration > Page > Edit).
  • 'post_date' - Sort by creation time.
  • 'post_modified' - Sort by time last modified.
  • 'ID' - Sort by numeric Page ID.
  • 'post_author' - Sort by the Page author's numeric ID.
  • 'post_name' - Sort alphabetically by Post slug.
menu_class 
(string) The div class the list is displayed in. Defaults to menu.
include 
(string) Only list pages identified with the corresponding id's, i.e. wp_page_menu('include=2,14') will list only pages with id's 2 and 14
exclude 
(string) Define a comma-separated list of Page IDs to be excluded from the list (example: 'exclude=3,7,31'). There is no default value. See the Exclude Pages from List example below.
exclude_tree 
(string) Define a comma-separated list of parent Page IDs to be excluded. Use this parameter to exclude a parent and all of that parent's child Pages. So 'exclude_tree=5' would exclude the parent Page 5, and its child (all descendant) Pages. (This parameter was added with Version 2.7, and it does not function as described as of version 2.8.1 - See bug report.)
echo 
(boolean) Toggles the display of the generated list of links or return the list as an HTML text string to be used in PHP. The default value is 1 (Display the generated list items). Valid values:
  • 0 (False)
  • 1 (True) - default
show_home 
(boolean) Add "Home" as the first item in the list of "Pages". The URL assigned to "Home" is pulled from the Blog address (URL) in Administration > Settings > General. The default value is 0 (do NOT display "Home" in the generated list). Valid values:
  • 0 (False) - default
  • 1 (True)
  • <any text> - Use this text as the link in place of "Home" (show_home is still considered true)
link_before 
(string) Sets the text or html that precedes the link text inside <a> tag.
link_after 
(string) Sets the text or html that follows the link text inside <a> tag.

Return Values

(string) 
The Menu's HTML, if the 'echo' parameter is set to false.

Examples

Display Home as a Page

The following example causes "Home" to be added to the beginning of the list of Pages displayed. In addition, the Pages wrapped in a div element, Page IDs 5, 9, and 23, are excluded from the list of Pages displayed, and the pages are listed in Page Order. The list is prefaced with the title, "Page Menu",

<h2>Page Menu</h2>
<?php wp_page_menu('show_home=1&exclude=5,9,23&menu_class=page-navi&sort_column=menu_order'); ?>

Display Home as a Page called Blog

The following example causes "Blog" (instead of "Home") to be added to the beginning of the list of Pages displayed:

<?php wp_page_menu( array( 'show_home' => 'Blog', 'sort_column' => 'menu_order' ) ); ?>

Display only Home

The following example displays just a link to "Home". Note that the include=9999' references a Page ID that does not exist so only a link for Home is displayed.

<?php wp_page_menu('show_home=1&include=9999'); ?>

Menu Item CSS Classes

The following classes are applied to menu items, i.e. to the HTML <li> tags, generated by wp_page_menu():

All Menu Items

  • .page_item
    This class is added to menu items that correspond to a static page.
  • .page-item-$ID
    This class is added to menu items that correspond to a static page, where $ID is the static page ID.

Current-Page Menu Items

  • .current_page_item
    This class is added to menu items that correspond to the currently rendered static page.

Current-Page Parent Menu Items

  • .current_page_parent
    This class is added to menu items that correspond to the hierarchical parent of the currently rendered static page.

Current-Page Ancestor Menu Items

  • .current_page_ancestor
    This class is added to menu items that correspond to a hierarchical ancestor of the currently rendered static page.

Notes

Change Log

  • Since: 2.7.0
  • 2.8.1 : sort_column parameter default changed from 'post_title' to 'menu_order, post_title'.

Source File

wp_page_menu() is located in wp-includes/post-template.php.

Related

List & Dropdown Functions

See also index of Function Reference and index of Template Tags.