wp_page_menu() – Function | Developer.WordPress.org

Displays or retrieves a list of pages with an optional home link.

Description

The arguments are listed below and part of the arguments are for wp_list_pages() function.
Check that function for more info on those arguments.

Parameters

$argsarray|stringoptional

Array or string of arguments to generate a page menu. See wp_list_pages() for additional arguments.

sort_column string
How to sort the list of pages. Accepts post column names.
Default ‘menu_order, post_title’.
menu_id string
ID for the div containing the page list. Default is empty string.
menu_class string
Class to use for the element containing the page list. Default 'menu'.
container string
Element to use for the element containing the page list. Default 'div'.
echo bool
Whether to echo the list or return it. Accepts true (echo) or false (return).
Default true.
show_home int|bool|string
Whether to display the link to the home page. Can just enter the text you’d like shown for the home link. 1|true defaults to 'Home'.
link_before string
The HTML or text to prepend to $show_home text.
link_after string
The HTML or text to append to $show_home text.
before string
The HTML or text to prepend to the menu. Default is <ul>.
after string
The HTML or text to append to the menu. Default is </ul>.
item_spacing string
Whether to preserve whitespace within the menu’s HTML. Accepts 'preserve' or 'discard'. Default 'discard'.
walker Walker
Walker instance to use for listing pages. Default empty which results in a Walker_Page instance being used.

More Arguments from wp_list_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'.

Default:array()

Return

void|string Void if 'echo' argument is true, HTML menu if 'echo' is false.

Source

function wp_page_menu( $args = array() ) {
	$defaults = array(
		'sort_column'  => 'menu_order, post_title',
		'menu_id'      => '',
		'menu_class'   => 'menu',
		'container'    => 'div',
		'echo'         => true,
		'link_before'  => '',
		'link_after'   => '',
		'before'       => '<ul>',
		'after'        => '</ul>',
		'item_spacing' => 'discard',
		'walker'       => '',
	);
	$args     = wp_parse_args( $args, $defaults );

	if ( ! in_array( $args['item_spacing'], array( 'preserve', 'discard' ), true ) ) {
		// Invalid value, fall back to default.
		$args['item_spacing'] = $defaults['item_spacing'];
	}

	if ( 'preserve' === $args['item_spacing'] ) {
		$t = "\t";
		$n = "\n";
	} else {
		$t = '';
		$n = '';
	}

	/**
	 * Filters the arguments used to generate a page-based menu.
	 *
	 * @since 2.7.0
	 *
	 * @see wp_page_menu()
	 *
	 * @param array $args An array of page menu arguments. See wp_page_menu()
	 *                    for information on accepted arguments.
	 */
	$args = apply_filters( 'wp_page_menu_args', $args );

	$menu = '';

	$list_args = $args;

	// Show Home in the menu.
	if ( ! empty( $args['show_home'] ) ) {
		if ( true === $args['show_home'] || '1' === $args['show_home'] || 1 === $args['show_home'] ) {
			$text = __( 'Home' );
		} else {
			$text = $args['show_home'];
		}
		$class = '';
		if ( is_front_page() && ! is_paged() ) {
			$class = 'class="current_page_item"';
		}
		$menu .= '<li ' . $class . '><a href="' . esc_url( home_url( '/' ) ) . '">' . $args['link_before'] . $text . $args['link_after'] . '</a></li>';
		// If the front page is a page, add it to the exclude list.
		if ( 'page' === get_option( 'show_on_front' ) ) {
			if ( ! empty( $list_args['exclude'] ) ) {
				$list_args['exclude'] .= ',';
			} else {
				$list_args['exclude'] = '';
			}
			$list_args['exclude'] .= get_option( 'page_on_front' );
		}
	}

	$list_args['echo']     = false;
	$list_args['title_li'] = '';
	$menu                 .= wp_list_pages( $list_args );

	$container = sanitize_text_field( $args['container'] );

	// Fallback in case `wp_nav_menu()` was called without a container.
	if ( empty( $container ) ) {
		$container = 'div';
	}

	if ( $menu ) {

		// wp_nav_menu() doesn't set before and after.
		if ( isset( $args['fallback_cb'] ) &&
			'wp_page_menu' === $args['fallback_cb'] &&
			'ul' !== $container ) {
			$args['before'] = "<ul>{$n}";
			$args['after']  = '</ul>';
		}

		$menu = $args['before'] . $menu . $args['after'];
	}

	$attrs = '';
	if ( ! empty( $args['menu_id'] ) ) {
		$attrs .= ' id="' . esc_attr( $args['menu_id'] ) . '"';
	}

	if ( ! empty( $args['menu_class'] ) ) {
		$attrs .= ' class="' . esc_attr( $args['menu_class'] ) . '"';
	}

	$menu = "<{$container}{$attrs}>" . $menu . "</{$container}>{$n}";

	/**
	 * Filters the HTML output of a page-based menu.
	 *
	 * @since 2.7.0
	 *
	 * @see wp_page_menu()
	 *
	 * @param string $menu The HTML output.
	 * @param array  $args An array of arguments. See wp_page_menu()
	 *                     for information on accepted arguments.
	 */
	$menu = apply_filters( 'wp_page_menu', $menu, $args );

	if ( $args['echo'] ) {
		echo $menu;
	} else {
		return $menu;
	}
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_page_menu’, string $menu, array $args ): Filters the HTML output of a page-based menu.
apply_filters( ‘wp_page_menu_args’, array $args ): Filters the arguments used to generate a page-based menu.

Uses	Description
is_front_page()`wp-includes/query.php`	Determines whether the query is for the front page of the site.
is_paged()`wp-includes/query.php`	Determines whether the query is for a paged result and not for the first page.
wp_list_pages()`wp-includes/post-template.php`	Retrieves or displays a list of pages (or hierarchical post type items) in list (li) format.
sanitize_text_field()`wp-includes/formatting.php`	Sanitizes a string from user input or from the database.
esc_url()`wp-includes/formatting.php`	Checks and cleans a URL.
esc_attr()`wp-includes/formatting.php`	Escaping for HTML attributes.
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.
home_url()`wp-includes/link-template.php`	Retrieves the URL for the current site where the front end is accessible.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.
get_option()`wp-includes/option.php`	Retrieves an option value based on an option name.

Show 7 more Show less

Changelog

Version	Description
4.7.0	Added the `item_spacing` argument.
4.4.0	Added `menu_id`, `container`, `before`, `after`, and `walker` arguments.
2.7.0	Introduced.

User Contributed Notes

Skip to note 5 content

Codex 10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
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'); ?>
```
Log in to add feedback
Skip to note 6 content

Codex 10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
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' ) ); ?>
```
Log in to add feedback
Skip to note 7 content

Codex 10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
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'); ?>
```
Log in to add feedback
Skip to note 8 content

gabbsmo 2 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

$args['show_home'] = false will not always work as it is often overriden by themes, including default themes. It will also set the class on the wrapping block element, not the root level unorded list, like wp_nav_menu. If you want your styles for wp_nav_menu to work, I recommend that you use wp_list_pages with your own wrapper.

Log in to add feedback

wp_page_menu( array|string $args = array() ): void|string

In this article