Title: wp_page_menu Published: April 25, 2014 Last modified: August 20, 2026 --- # wp_page_menu( array|string $args = array() ): void|string ## In this article * [Description](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#description) * [Parameters](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#parameters) * [Return](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#return) * [Source](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#source) * [Hooks](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#hooks) * [Related](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#related) * [Changelog](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#changelog) * [User Contributed Notes](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#user-contributed-notes) [ Back to top](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#wp--skip-link--target) Displays or retrieves a list of pages with an optional home link. ## 󠀁[Description](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#description)󠁿 The arguments are listed below and part of the arguments are for [wp_list_pages()](https://developer.wordpress.org/reference/functions/wp_list_pages/) function. Check that function for more info on those arguments. ## 󠀁[Parameters](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#parameters)󠁿 `$args`array|stringoptional Array or string of arguments to generate a page menu. See [wp_list_pages()](https://developer.wordpress.org/reference/functions/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 ``. * `item_spacing` string * Whether to preserve whitespace within the menu’s HTML. Accepts `'preserve'` or`' discard'`. Default `'discard'`. * `walker` [Walker](https://developer.wordpress.org/reference/classes/walker/) * [Walker](https://developer.wordpress.org/reference/classes/walker/) instance to use for listing pages. Default empty which results in a [Walker_Page](https://developer.wordpress.org/reference/classes/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](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#return)󠁿 void|string Void if `'echo'` argument is true, HTML menu if `'echo'` is false. ## 󠀁[Source](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#source)󠁿 ```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' => '', '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 .= '
  • ' . $args['link_before'] . $text . $args['link_after'] . '
    • '; // 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'] = "'; } $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 . "{$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](https://developer.wordpress.org/reference/files/wp-includes/post-template.php/) [View on Trac](https://core.trac.wordpress.org/browser/tags/7.1/src/wp-includes/post-template.php#L1426) [View on GitHub](https://github.com/WordPress/wordpress-develop/blob/7.1/src/wp-includes/post-template.php#L1426-L1547) ## 󠀁[Hooks](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#hooks)󠁿 [apply_filters( ‘wp_page_menu’, string $menu, array $args )](https://developer.wordpress.org/reference/hooks/wp_page_menu/) Filters the HTML output of a page-based menu. [apply_filters( ‘wp_page_menu_args’, array $args )](https://developer.wordpress.org/reference/hooks/wp_page_menu_args/) Filters the arguments used to generate a page-based menu. ## 󠀁[Related](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#related)󠁿 | Uses | Description | | [is_front_page()](https://developer.wordpress.org/reference/functions/is_front_page/)`wp-includes/query.php` | Determines whether the query is for the front page of the site. | | [is_paged()](https://developer.wordpress.org/reference/functions/is_paged/)`wp-includes/query.php` | Determines whether the query is for a paged result and not for the first page. | | [wp_list_pages()](https://developer.wordpress.org/reference/functions/wp_list_pages/)`wp-includes/post-template.php` | Retrieves or displays a list of pages (or hierarchical post type items) in list (li) format. | | [__()](https://developer.wordpress.org/reference/functions/__/)`wp-includes/l10n.php` | Retrieves the translation of $text. | | [sanitize_text_field()](https://developer.wordpress.org/reference/functions/sanitize_text_field/)`wp-includes/formatting.php` | Sanitizes a string from user input or from the database. | | [esc_url()](https://developer.wordpress.org/reference/functions/esc_url/)`wp-includes/formatting.php` | Checks and cleans a URL. | | [esc_attr()](https://developer.wordpress.org/reference/functions/esc_attr/)`wp-includes/formatting.php` | Escaping for HTML attributes. | | [wp_parse_args()](https://developer.wordpress.org/reference/functions/wp_parse_args/)`wp-includes/functions.php` | Merges user defined arguments into defaults array. | | [home_url()](https://developer.wordpress.org/reference/functions/home_url/)`wp-includes/link-template.php` | Retrieves the URL for the current site where the front end is accessible. | | [apply_filters()](https://developer.wordpress.org/reference/functions/apply_filters/)`wp-includes/plugin.php` | Calls the callback functions that have been added to a filter hook. | | [get_option()](https://developer.wordpress.org/reference/functions/get_option/)`wp-includes/option.php` | Retrieves an option value based on an option name. | [Show 8 more](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#) [Show less](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#) ## 󠀁[Changelog](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#changelog)󠁿 | Version | Description | | [4.7.0](https://developer.wordpress.org/reference/since/4.7.0/) | Added the `item_spacing` argument. | | [4.4.0](https://developer.wordpress.org/reference/since/4.4.0/) | Added `menu_id`, `container`, `before`, `after`, and `walker` arguments. | | [2.7.0](https://developer.wordpress.org/reference/since/2.7.0/) | Introduced. | ## 󠀁[User Contributed Notes](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#user-contributed-notes)󠁿 1. [Skip to note 5 content](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#comment-content-527) 2. [Codex](https://profiles.wordpress.org/codex/) [ 11 years ago ](https://developer.wordpress.org/reference/functions/wp_page_menu/#comment-527) 3. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_page_menu%2F%23comment-527) Vote results for this note: 1[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_page_menu%2F%23comment-527) 4. **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”. 5. ```php

    Page Menu

    ``` 6. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_page_menu%2F%3Freplytocom%3D527%23feedback-editor-527) 7. [Skip to note 6 content](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#comment-content-528) 8. [Codex](https://profiles.wordpress.org/codex/) [ 11 years ago ](https://developer.wordpress.org/reference/functions/wp_page_menu/#comment-528) 9. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_page_menu%2F%23comment-528) Vote results for this note: 1[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_page_menu%2F%23comment-528) 10. **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: 11. ```php 'Blog', 'sort_column' => 'menu_order' ) ); ?> ``` 12. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_page_menu%2F%3Freplytocom%3D528%23feedback-editor-528) 13. [Skip to note 7 content](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#comment-content-529) 14. [Codex](https://profiles.wordpress.org/codex/) [ 11 years ago ](https://developer.wordpress.org/reference/functions/wp_page_menu/#comment-529) 15. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_page_menu%2F%23comment-529) Vote results for this note: 1[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_page_menu%2F%23comment-529) 16. **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. 17. ```php ``` 18. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_page_menu%2F%3Freplytocom%3D529%23feedback-editor-529) 19. [Skip to note 8 content](https://developer.wordpress.org/reference/functions/wp_page_menu/?output_format=md#comment-content-6827) 20. [gabbsmo](https://profiles.wordpress.org/gabbsmo/) [ 3 years ago ](https://developer.wordpress.org/reference/functions/wp_page_menu/#comment-6827) 21. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_page_menu%2F%23comment-6827) Vote results for this note: 0[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_page_menu%2F%23comment-6827) 22. `$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. 23. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_page_menu%2F%3Freplytocom%3D6827%23feedback-editor-6827) You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_page_menu%2F) before being able to contribute a note or feedback.