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

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;
	}
}

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.

Changelog

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

User Contributed Notes

  1. Skip to note 5 content

    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'); ?>
  2. Skip to note 8 content

    $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.

You must log in before being able to contribute a note or feedback.