add_menu_page() │ WP 1.5.0

Add a top-level menu page to the Dashboard (next to Posts, Pages, Users etc).

It is used to create a dashboard menu item and attach a function to this item that will be responsible for its page.

No Hooks.

Return

String. The resulting page's hook_suffix.

Usage

add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function, $icon_url, $position );

$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. List of roles and capabilities.

$menu_slug(string) (required)

The slug name to refer to this menu. Should be unique and only include lowercase alphanumeric, dashes, and underscores characters.

If the $function parameter is not specified, you need to specify the name of the PHP file (relative to the plugin directory) in this parameter. Specified file will be responsible for the output of the page content of this menu item.

You can also specify an arbitrary link (URL). In this case, you will go to the URL by clicking the menu item.

$function(callable)

The function to be called to output the content for this page.

This is an optional parameter and if it is not specified, WordPress expects the PHP file from $menu_slug parameter generate the admin menu page.

There are two variants to specify this parameter:

1. If the function is a class method:
   array( $this, 'function_name' )
   or static:
   array( __CLASS__, 'function_name' ).
2. Function name as a string.

Default: ''

$icon_url(string)

The URL to the icon to be used for this menu item.

• Image ― if you want to use a custom icon, you can specify a URL to the icon. For example, plugin_dir_url( __FILE__ ) .'plugin-icon.png'. The size of the icon should be 20x20 pixels or less.

• dashicons ― since WP 3.8, you can use special dashicons icons. Just select one from the list and use its name. For example, dashicons-dashboard.

• base64 ― since WP 3.8, you can specify base64 encoded SVG image: base64-encoded SVG. In this case this parameter should begin with data:image/svg+xml;base64,.... In this case, the icon will be specified as a background-image.

  IMPORTANT: since WP 6.0 only SVG formats can be specified this way (png, jpg will not work).

• none ― to leave div.wp-menu-image empty, to add icon later from CSS.

• '' — By default, when used an empty string '', dashicons-dashboard from the dashicons is used, and the CSS class menu-icon-generic is added.

Default: ''

$position(int)

The number that determines the menu item position. The larger the number, the lower the menu item will be.

Attention! If two items use the same digit-position, one of the menu items can be overwritten and only one of the two items will be shown. To avoid such conflict, you can use float values instead of integers: 63.3 instead of 63. Use quotes: "63.3".

By default, the menu item will be added to the end of the list.

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

Default: null

Examples

<?php
add_action('admin_menu', function(){
	add_menu_page( 'Additional site settings', 'Additional settings', 'manage_options', 'site-options', 'add_my_setting', '', 4 );
} );

function add_my_setting(){
	?>
	<div class="wrap">
		<h2><?php echo get_admin_page_title() ?></h2>

		<?php
		// settings_errors() won't work on other than options pages
		if( get_current_screen()->parent_base !== 'options-general' )
			settings_errors('option_name');
		?>

		<form action="options.php" method="POST">
			<?php
				settings_fields("opt_group");     // hidden protection fields
				do_settings_sections("opt_page"); // settings section
				submit_button();
			?>
		</form>
	</div>
	<?php

}

add_action( 'admin_menu', 'register_my_custom_menu_page' );
function register_my_custom_menu_page(){
	add_menu_page(
		'custom menu title', 'custom menu', 'manage_options', 'myplugin/myplugin-admin.php', '', plugins_url( 'myplugin/images/icon.png' ), 6
	);
}

<?php
	echo "Some page code.";
?>

add_action( 'admin_menu', 'register_my_custom_menu_page' );
function register_my_custom_menu_page(){
	add_menu_page(
		'custom menu title', 'custom menu', 'manage_options', 'custompage', 'my_custom_menu_page', plugins_url( 'myplugin/images/icon.png' ), 6
	);
}

function my_custom_menu_page(){
	echo "Some page code.";
}

global $admin_page_hooks;

if( isset($admin_page_hooks['menu_slug']) ){
	add_submenu_page( ... );
}
else {
	add_menu_page( ..., ..., ..., 'menu_slug' );
	add_submenu_page( ... );
}

/**
 * Finds the specified menu or submenu item item in the dashboard.
 *
 * Use after 'admin_menu' hook.
 *
 * Usage example: if( is_admin_menu_item_exists('options-general.php') ){  }
 *
 * @param  string  $handle        Menu slug. Specified in 4 parameter of add_menu_page() or add_submenu_page()
 * @param  boolean [$sub = false] Is menu or submenu ID specified?
 * @return boolean Whether a menu item exists
 */
function is_admin_menu_item_exists( $handle, $sub = false ){

	if( !is_admin() || (defined('DOING_AJAX') && DOING_AJAX) )
		return false;

	global $menu, $submenu;

	$check_menu = $sub ? $submenu : $menu;

	if( empty($check_menu) )
		return false;

	foreach( $check_menu as $k => $item ){
		if( $sub ){
			foreach( $item as $sm ){
			  if( $handle == $sm[2] )
				return true;
			}
		}
		elseif( $handle == $item[2] )
			return true;
	}

	return false;
}

add_action( 'admin_menu', 'change_menu' );

function change_menu() {

	$post_id  = 393;
	$url_edit = get_edit_post_link( $post_id );

	if ( $url_edit ) {
		add_menu_page( '', 'My article', 'edit_posts', $url_edit, '', '', 5 );
	}
}

Add Your Own Example