add_menu_page ( string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = '', string $icon_url = '', int $position = null )

Add a top-level menu page.

This function takes a capability which will be used to determine whether or not a page is included in the menu.

The function which is hooked in to handle the output of the page must check that the user has the required capability as well.

Return: (string) The resulting page's hook_suffix.

Source file: wp-admin/includes/plugin.php

View source


Parameters

$page_title

(string) (Required) The text to be displayed in the title tags of the page when the menu is selected.

$menu_title

(string) (Required) The text to be used for the menu.

$capability

(string) (Required) The capability required for this menu to be displayed to the user.

$menu_slug

(string) (Required) The slug name to refer to this menu by (should be unique for this menu).

$function

(callable) (Optional) The function to be called to output the content for this page.

Default value: ''

$icon_url

(string) (Optional) The URL to the icon to be used for this menu.
* Pass a base64-encoded SVG using a data URI, which will be colored to match the color scheme. This should begin with 'data:image/svg+xml;base64,'.
* Pass the name of a Dashicons helper class to use a font icon, e.g. 'dashicons-chart-pie'.
* Pass 'none' to leave div.wp-menu-image empty so an icon can be added via CSS.

Default value: ''

$position

(int) (Optional) The position in the menu order this one should appear.

Default value: null


More Information

Notes

  • Important Note: If two menu items use the same position, only one of them will be displayed. In most cases, it’s better to use add_object_page(), which will automatically position the new page alongside other custom post types, avoiding any conflicts. Risk of conflict can also be reduced by using strings values instead of integers, e.g. ‘63.3’ (string) instead of 63 (integer).
  • If you’re running into the “You do not have sufficient permissions to access this page” error, then you’ve hooked too early. The hook you should use is admin_menu.
  • If you only want to move existing admin menu items to different positions, you can use the admin_menu hook to unset menu items from their current positions in the global $menu and $submenu variables (which are arrays), and reset them elsewhere in the array.
  • This function takes a ‘capability’ (see Roles and Capabilities) which will be used to determine whether or not a page is included in the menu. The function which is hooked in to handle the output of the page must check that the user has the required ‘capability’ as well.
  • If you are using the Settings API to save data, and need the user to be other than the administrator, will need to modify the permissions via the hook option_page_capability_{$option_group}, where $option_group is the same as option_group in register_setting() . Check out the Settings API.

Example allowing an editor to save data:

// Register settings using the Settings API 
function wpdocs_register_my_setting() {
	register_setting( 'my-options-group', 'my-option-name', 'intval' ); 
} 
add_action( 'admin_init', 'wpdocs_register_my_setting' );

// Modify capability
function wpdocs_my_page_capability( $capability ) {
	return 'edit_others_posts';
}
add_filter( 'option_page_capability_my-options-group', 'wpdocs_my_page_capability' );

Menu Structure

Default: bottom of menu structure

  • 2 – Dashboard
  • 4 – Separator
  • 5 – Posts
  • 10 – Media
  • 15 – Links
  • 20 – Pages
  • 25 – Comments
  • 59 – Separator
  • 60 – Appearance
  • 65 – Plugins
  • 70 – Users
  • 75 – Tools
  • 80 – Settings
  • 99 – Separator

For the Network Admin menu, the values are different:

  • 2 – Dashboard
  • 4 – Separator
  • 5 – Sites
  • 10 – Users
  • 15 – Themes
  • 20 – Plugins
  • 25 – Settings
  • 30 – Updates
  • 99 – Separator


Source

function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $icon_url = '', $position = null ) {
	global $menu, $admin_page_hooks, $_registered_pages, $_parent_pages;

	$menu_slug = plugin_basename( $menu_slug );

	$admin_page_hooks[$menu_slug] = sanitize_title( $menu_title );

	$hookname = get_plugin_page_hookname( $menu_slug, '' );

	if ( !empty( $function ) && !empty( $hookname ) && current_user_can( $capability ) )
		add_action( $hookname, $function );

	if ( empty($icon_url) ) {
		$icon_url = 'dashicons-admin-generic';
		$icon_class = 'menu-icon-generic ';
	} else {
		$icon_url = set_url_scheme( $icon_url );
		$icon_class = '';
	}

	$new_menu = array( $menu_title, $capability, $menu_slug, $page_title, 'menu-top ' . $icon_class . $hookname, $hookname, $icon_url );

	if ( null === $position ) {
		$menu[] = $new_menu;
	} elseif ( isset( $menu[ "$position" ] ) ) {
	 	$position = $position + substr( base_convert( md5( $menu_slug . $menu_title ), 16, 10 ) , -5 ) * 0.00001;
		$menu[ "$position" ] = $new_menu;
	} else {
		$menu[ $position ] = $new_menu;
	}

	$_registered_pages[$hookname] = true;

	// No parent as top level
	$_parent_pages[$menu_slug] = false;

	return $hookname;
}


User Contributed Notes

  1. Examples
    Add a custom menu item to the WordPress admin menu, for a user with administrator capability:

    Method 1:

    /**
     * Register a custom menu page.
     */
    function wpdocs_register_my_custom_menu_page() {
    	add_menu_page(
    		__( 'Custom Menu Title', 'textdomain' ),
    		'custom menu',
    		'manage_options',
    		'myplugin/myplugin-admin.php',
    		'',
    		plugins_url( 'myplugin/images/icon.png' ),
    		6
    	);
    }
    add_action( 'admin_menu', 'wpdocs_register_my_custom_menu_page' );
    

    With this method the page-generating code should be located in myplugin/myplugin-admin.php:

    <?php esc_html_e( 'Admin Page Test', 'textdomain' ); ?>
    

    Method 2:

    /**
     * Register a custom menu page.
     */
    function wpdocs_register_my_custom_menu_page(){
    	add_menu_page( 
    		__( 'Custom Menu Title', 'textdomain' ),
    		'custom menu',
    		'manage_options',
    		'custompage',
    		'my_custom_menu_page',
    		plugins_url( 'myplugin/images/icon.png' ),
    		6
    	); 
    }
    add_action( 'admin_menu', 'wpdocs_register_my_custom_menu_page' );
    
    /**
     * Display a custom menu page
     */
    function my_custom_menu_page(){
    	esc_html_e( 'Admin Page Test', 'textdomain' );	
    }
    
  2. /**
     * Create admin Page to list unsubscribed emails.
     */
     // Hook for adding admin menus
     add_action('admin_menu', 'wpdocs_unsub_add_pages');
    
     // action function for above hook
    
    /**
     * Adds a new top-level page to the administration menu.
     */
    function wpdocs_unsub_add_pages() {
         add_menu_page(
    	 	__( 'Unsub List', 'textdomain' ),
    		__( 'Unsub Emails','textdomain' ),
    		'manage_options',
    		'wpdocs-unsub-email-list',
    		'wpdocs_unsub_page_callback',
    		''
    	);
    }
    
    /**
     * Disply callback for the Unsub page.
     */
     function wpdocs_unsub_page_callback() {
         echo 'Unsubscribe Email List';
     }
     

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