wp_page_menu() │ WP 2.7.0

Outputs a list of static blog pages as links to the corresponding pages. An analogue of wp_list_pages(), but there is an option to add a "home" link at the beginning.

The function is typically used in the header and sidebar to display the menu of static pages. However, it can also be used in other places in the template.

Uses: wp_list_pages()
Hooks from the function

Returns

null|String. Outputs the HTML code of the menu. If the echo parameter is set to false, it returns a string.

Usage

wp_page_menu( $args );

Arguments of the $args parameter

For a complete list of arguments, see the function description wp_list_pages(). Below are some of them:

show_home(boolean)
The "Home" link at the beginning of the list of pages. 0 (false) - do not show the link; 1 (true) - add the link.
Default: false
depth(int)

This parameter controls the level of nesting of child pages that will be included in the list. By default 0 (show all child pages, including double and more nesting).

  • 0 (default) Include all levels of nested pages in the list and display them in a tree-like view.

  • -1 Include all levels of nested pages in the list, but do not show nesting (tree-like display of the list is disabled, the list will be shown as flat).

  • 1 Show only the first nested pages, i.e., first-level child pages.

  • 2, 3, etc. Include child pages of level 2, 3, etc.…
sort_column(string)

Sort the list by specified fields. By default, the list is sorted by the order number specified when publishing the page (menu order) and by titles (post_title), in alphabetical order. Any column value from the wp_post table can be used for sorting. Multiple parameters can be specified via a comma, according to which the list will then be sorted. Some popular sorting fields:

  • post_title - sort by title (in alphabetical order);
  • menu_order - sort by the order specified in the admin panel on the edit "static page" screen;
  • post_date - sort by the creation date of the "static page";
  • post_modified - sort by the page modification date;
  • ID - sort by the post ID in the Database (by ID);
  • post_author - sort by author IDs;
  • post_name - sort alphabetically by the post's alternative name (usually the transliteration of the title).

Default: 'menu_order, post_title'

menu_class(string)
The name of the CSS class for the wrapping menu HTML tag DIV (class="menu").
Default: 'menu'
menu_id(string)
ID for the <div> tag. Since version 4.4.
Default: ''
container(string)
The element that will contain the list of pages. Since version 4.4.
Default: 'div'
include(string)
Show only specified pages in the list. In the parameter, specify the IDs of the static pages to be displayed in the list, separated by commas.
This parameter overrides the parameters related to list formation, as it creates a list only from the specified pages. The parameters: exclude, child_of, depth, meta_key, meta_value, authors are overridden.
Default: ''
exclude(string)
In this parameter, specify the IDs of the pages that we do not want to be included in the list, for example: exclude=3,7,31.
Default: ''
exclude_tree(string)
Specify the parent page IDs that you want to exclude from the list, separated by commas. All nested (child) pages of the specified IDs will also be excluded. That is, this parameter excludes the entire tree of pages from the list.
Added in version 2.7.
Default: ''
echo(boolean)
Output the result on the screen (true) or return for processing (false).
Default: true
link_before(string)
Specify here the text or HTML code that will be inserted before the link text (inside the <a> tag). Added in version 2.7.
Default: ""
link_after(string)
Specify here the text or HTML code that will be inserted after the link text (inside the <a> tag). Added in version 2.7.
Default: ""
before(string)
HTML or text to place before the menu. Since version 4.4.
Default: '<ul>'
after(string)
HTML or text to place after the menu. Since version 4.4.
Default: '</ul>'
item_spacing(string)
Whether to keep line breaks in the HTML code of the menu. Can be: preserve or discard. Since WP 4.7.
Default: 'preserve'
walker(Walker)
An instance of the Walker object that will build the menu. Since version 4.4.
Default: empty (Walker_Page)

Examples

0

#1 Home link

Let's add a link to the homepage (show_home=1). Also, exclude pages (exclude=5,9,23), add your own class to the wrapping div (menu_class=page-navi) and sort links by column (sort_column=menu_order):

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

#2 Specify the name of the link to the home page (anchor): 

<?php wp_page_menu('show_home=Home page' ); ?>

or like this

<?php wp_page_menu( array('show_home' => 'Home' ) ); ?>
0

#3 Display only the link to the home page: 

wp_page_menu( 'show_home=1&include=9999' );

CSS classes used in the menu

CSS classes added to <li> menu items for each link, depending on its value in the menu.

.page_item - for all list items that lead to a static page. Thus, this class is not specified for the home page.

.page-item-$ID - for all list items. $ID is the ID of the page.

.current_page_item - for the page currently being viewed.

.current_page_parent - for the parent page of the page currently being viewed (the current page will be a child).

.current_page_ancestor - for all pages that are at the same level as the currently viewed page.

Changelog

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

wp_page_menu() code WP 6.9.1

wp-includes/post-template.php 
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;
	}
}

List (wp_list)

Pages