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

Description

Parameters

$argsarray|stringoptional

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

• $sort_columnstringdefault: 'menu_order, post_title'

  How to sort the list of pages. Accepts post column names.

• $menu_idstringdefault: is empty string

  ID for the div containing the page list.

• $menu_classstringdefault: 'menu'

  Class to use for the element containing the page list.

• $containerstringdefault: 'div'

  Element to use for the element containing the page list.

• $echobooldefault: true

  Whether to echo the list or return it. Accepts true (echo) or false (return).

• $show_homeint|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_beforestringdefault: empty

  The HTML or text to prepend to $show_home text.

• $link_afterstringdefault: empty

  The HTML or text to append to $show_home text.

• $beforestringdefault: is ''

  The HTML or text to prepend to the menu.

• $afterstringdefault: is ''

  The HTML or text to append to the menu.

• $item_spacingstringdefault: 'discard'

  Whether to preserve whitespace within the menu's HTML. Accepts 'preserve' or 'discard'.

• $walkerWalkerdefault: empty which results in a Walker_Page instance being used

  Walker instance to use for listing pages.

Return

void|string

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

Hooks fired · 2

2 hooks fire while wp_page_menu() runs, in this order:

1. 1
   apply_filters( wp_page_menu_args )filterline 1465 (+39 into the body)

   Filters the arguments used to generate a page-based menu.

2. 2
   apply_filters( wp_page_menu )filterline 1540 (+114 into the body)

   Filters the HTML output of a page-based menu.

Uses · 11

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

Source

View on Trac ↗View on GitHub ↗

1426function wp_page_menu( $args = array() ) {1427	$defaults = array(1428		'sort_column'  => 'menu_order, post_title',1429		'menu_id'      => '',1430		'menu_class'   => 'menu',1431		'container'    => 'div',1432		'echo'         => true,1433		'link_before'  => '',1434		'link_after'   => '',1435		'before'       => '<ul>',1436		'after'        => '</ul>',1437		'item_spacing' => 'discard',1438		'walker'       => '',1439	);1440	$args     = wp_parse_args( $args, $defaults );1441 1442	if ( ! in_array( $args['item_spacing'], array( 'preserve', 'discard' ), true ) ) {1443		// Invalid value, fall back to default.1444		$args['item_spacing'] = $defaults['item_spacing'];1445	}1446 1447	if ( 'preserve' === $args['item_spacing'] ) {1448		$t = "\t";1449		$n = "\n";1450	} else {1451		$t = '';1452		$n = '';1453	}1454 1455	/**1456	 * Filters the arguments used to generate a page-based menu.1457	 *1458	 * @since 2.7.01459	 *1460	 * @see wp_page_menu()1461	 *1462	 * @param array $args An array of page menu arguments. See wp_page_menu()1463	 *                    for information on accepted arguments.1464	 */1465	$args = apply_filters( 'wp_page_menu_args', $args );1466 1467	$menu = '';1468 1469	$list_args = $args;1470 1471	// Show Home in the menu.1472	if ( ! empty( $args['show_home'] ) ) {1473		if ( true === $args['show_home'] || '1' === $args['show_home'] || 1 === $args['show_home'] ) {1474			$text = __( 'Home' );1475		} else {1476			$text = $args['show_home'];1477		}1478		$class = '';1479		if ( is_front_page() && ! is_paged() ) {1480			$class = 'class="current_page_item"';1481		}1482		$menu .= '<li ' . $class . '><a href="' . esc_url( home_url( '/' ) ) . '">' . $args['link_before'] . $text . $args['link_after'] . '</a></li>';1483		// If the front page is a page, add it to the exclude list.1484		if ( 'page' === get_option( 'show_on_front' ) ) {1485			if ( ! empty( $list_args['exclude'] ) ) {1486				$list_args['exclude'] .= ',';1487			} else {1488				$list_args['exclude'] = '';1489			}1490			$list_args['exclude'] .= get_option( 'page_on_front' );1491		}1492	}1493 1494	$list_args['echo']     = false;1495	$list_args['title_li'] = '';1496	$menu                 .= wp_list_pages( $list_args );1497 1498	$container = sanitize_text_field( $args['container'] );1499 1500	// Fallback in case `wp_nav_menu()` was called without a container.1501	if ( empty( $container ) ) {1502		$container = 'div';1503	}1504 1505	if ( $menu ) {

History

Introduced in 2.7.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/post-template.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.