About add_menu_page () function

When building custom WordPress plugins or themes, one of the most common tasks is adding new pages to the WordPress admin dashboard. This is essential for providing settings, options, or functionality interfaces that site administrators can manage. WordPress makes this easy through its built-in functions, among which add_menu_page() is a primary tool.

What is add_menu_page()?

The add_menu_page() function is a WordPress core function that allows developers to add a new top-level menu item to the WordPress admin sidebar. This menu item, when clicked, loads a custom admin page created by the developer. This is particularly useful for plugins or themes that require an interface to manage their options or display reports.

In simple terms, add_menu_page() helps you create your own section in the WordPress admin dashboard for your plugin or custom feature.

Why Use add_menu_page()?

• Centralize plugin settings: It allows you to create a dedicated admin page for your plugin settings rather than mixing them inside existing menus.

• Better user experience: A dedicated menu makes it easier for users to find and access your plugin’s features.

• Extend WordPress Admin: Customize the admin interface to suit your specific needs.

• Control access: You can restrict access to the menu and page based on user roles and capabilities.

How to Use add_menu_page()

Syntax

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

Parameters Breakdown

• $page_title
  The text that appears in the browser’s title bar and at the top of the page when the menu is active.

• $menu_title
  The label for the menu item in the WordPress admin sidebar.

• $capability
  A string representing the minimum user capability required to view this menu. Commonly manage_options (admins only) or custom capabilities.

• $menu_slug
  A unique slug (string) identifier for your menu page, used in the URL to access the page.

• $function (optional)
  The callback function that outputs the content of the menu page. If omitted, the page will be blank.

• $icon_url (optional)
  URL to a custom icon image or a Dashicons class name (e.g., dashicons-admin-generic) to display next to the menu title.

• $position (optional)
  Integer value determining the menu position/order in the sidebar. Lower numbers appear higher.

Example: Adding a Custom Top-Level Admin Menu

Let’s see a practical example of how to add a menu called “My Plugin” to the WordPress admin sidebar.

add_action('admin_menu', 'my_plugin_add_admin_menu');

function my_plugin_add_admin_menu() {
add_menu_page(
'My Plugin Settings', // Page title
'My Plugin', // Menu title
'manage_options', // Capability
'my-plugin', // Menu slug
'my_plugin_settings_page', // Callback function
'dashicons-admin-generic', // Icon (WordPress Dashicon)
6 // Position in the menu
);
}

function my_plugin_settings_page() {
?>
<div class="wrap">
<h1>My Plugin Settings</h1>
<p>Welcome to the plugin settings page. Customize your plugin here.</p>
</div>
<?php
}

How this works:

• We hook our function to admin_menu, which WordPress runs when it builds the admin menu.

• We call add_menu_page() inside that function with parameters defining the menu page.

• The menu appears in the sidebar with the label “My Plugin” and an icon.

• When clicked, it loads the page generated by my_plugin_settings_page().

Customizing the Menu Icon

You can use WordPress Dashicons by passing their class name as the icon URL parameter. Some examples:

• dashicons-admin-generic (default gear icon)

• dashicons-admin-home (home icon)

• dashicons-welcome-add-page (plus icon)

Alternatively, use a URL to a custom image (ideally 20x20 pixels PNG or SVG):

add_menu_page(..., 'https://example.com/wp-content/uploads/my-icon.png', ...);

Positioning the Menu Item

The $position parameter controls the order the menu appears in the sidebar. Here are some common positions:

If your menu doesn’t appear exactly where you want, try adjusting the number.

Important Considerations

• Security & Permissions: Always use the correct capability to restrict access to your menu and page.

• Unique Menu Slug: Make sure the slug is unique to prevent conflicts with other plugins.

• Performance: Keep your callback function efficient to avoid slowing down the admin area.

• Localization: Use translation functions for titles and content if your plugin will support multiple languages.

Extending with Submenus

Often, plugins require multiple pages grouped under one main menu. Use add_submenu_page() to add submenu items under your main menu.

add_action('admin_menu', 'my_plugin_add_submenu');

function my_plugin_add_submenu() {
add_submenu_page(
'my-plugin', // Parent slug
'Submenu Page', // Page title
'Submenu', // Menu title
'manage_options', // Capability
'my-plugin-submenu', // Menu slug
'my_plugin_submenu_page' // Callback function
);
}

function my_plugin_submenu_page() {
echo '<h2>Submenu Page Content</h2>';
}

Summary

• add_menu_page() lets you add custom top-level menus to the WordPress admin.

• It provides control over title, permissions, icons, and position.

• The callback function outputs the page content.

• It’s a fundamental tool for creating rich plugin or theme admin interfaces.