Menu Icons: Dashicons and Custom SVGs

The $icon_url parameter in add_menu_page() sets the menu item icon. WordPress supports three icon specification methods:

Dashicons — the built-in WordPress icon set. Simply specify the CSS class, for example 'dashicons-admin-generic', 'dashicons-chart-area', 'dashicons-shield'. Over 200 icons are available.

Custom image — specify a PNG or SVG file URL. Optimal size is 20x20 pixels: get_template_directory_uri() . '/assets/icon.png'

Base64 SVG — inline SVG encoded as base64. Eliminates the need for a separate file:

Menu Positioning

The $position parameter determines where your menu item appears in the sidebar. WordPress reserves specific positions for standard items:

For your own menu, choose positions between standard items. Popular choices: 26 (between Comments and Appearance), 61 (between Appearance and Plugins), 81 (after Settings). If two plugins use the same position, WordPress appends a suffix to the slug of the last registered item.

add_submenu_page() — Submenus

The add_submenu_page() function adds a child item under an existing menu. The signature is similar to add_menu_page() but with an additional first parameter — the parent menu slug:

To add submenus to standard WordPress items, use these parent slugs:

add_plugins_page() and add_theme_page()

These two functions are wrappers around add_submenu_page() with a fixed parent. They exist for semantic clarity and to reduce the chance of parent slug errors.

add_plugins_page() adds an item to the Plugins menu:

add_theme_page() adds an item to the Appearance menu, ideal for theme options:

Both functions hook into admin_menu, like all other menu functions. Call order within the hook does not affect display order — WordPress sorts items by position and alphabetically.

The admin_menu Hook and Priorities

All menu creation functions must be called within the admin_menu hook. This hook fires after core loads but before the sidebar renders:

The hook priority (third parameter of add_action) determines when your menus are registered relative to other plugins. The default priority is 10. To ensure your menu appears after all standard items, use a higher priority:

Priority 99 guarantees your code runs after most plugins, allowing you to override or extend existing menus.

Conditional Menu Display

Sometimes a menu should only be visible to certain users or under specific conditions. WordPress does not provide a built-in mechanism for conditional menu hiding beyond capability checks, but there are two workarounds.

Method 1: Role check inside the hook. Wrap the add_menu_page() call in a check:

Method 2: Remove menu items selectively. Use remove_menu_page() to hide items:

This pattern is useful in multi-tier systems where some settings are visible to administrators and others to content editors. WordPress checks capabilities when loading the menu and only shows items to users who meet at least one condition.

Custom Capabilities

When standard WordPress capabilities are insufficient, you can create your own. This is especially relevant for plugins with specialized functionality. Register a custom capability on plugin activation:

Multi-Page Menu Structure

As a plugin grows, a single settings page stops fitting all functionality. The typical pattern for large plugins is one top-level menu with multiple submenus, each leading to its own settings page:

Note an important detail: the first submenu uses the same slug ('sandbox-pro') as the parent menu. When the submenu slug matches the parent, WordPress does not create a duplicate entry. This is the standard technique for having the parent menu click lead to the Dashboard page while other items lead to corresponding sub-pages.

Overriding Standard Pages via Menus

Sometimes you need to replace a standard WordPress page with your own implementation — for example, a custom post list or an analytics dashboard. Use the technique of matching the slug with a standard menu but providing a custom callback:

This code replaces the default Dashboard with your custom one while preserving the original menu item name and position. Users will not notice any interface difference but will see your custom page instead of the standard one. Important: if you override a critical page like Dashboard, make sure your version does not lose original functionality such as the At a Glance widget or update notification blocks.

Multisite Menu Considerations

In WordPress Multisite, menu behavior changes. Some standard items (Tools, Settings) are only available to super admins, not individual site administrators. If your plugin must work in a multisite environment, keep the following in mind:

Use is_multisite() to check the environment and adapt capabilities accordingly. In multisite, a site administrator has manage_options but not manage_network (reserved for super admins). A plugin that hardcodes manage_network will be invisible to site administrators even if they need its functionality:

Menu items registered with parent 'settings.php' (network settings) only appear in the network admin and only for super admins. This is useful for creating network-level configuration pages that must not be visible to individual site administrators.

Debugging WordPress Admin Menus

When menus do not appear, the first step is to verify they are registered correctly. The global $menu and $submenu arrays contain all registered menu items:

Check the HTML source of any admin page to see the dumped arrays. Look for your slug in both arrays — if it is missing, check that your function is hooked to admin_menu and that the hook is actually firing. For more advanced debugging, use the Admin Menu Editor plugin or Query Monitor, both of which visualize the menu structure and indicate which capability is missing for a specific item. This makes troubleshooting menu visibility issues a matter of seconds rather than hours of trial and error. Remember that the admin menu is rebuilt on every page load, so any changes to menu registration take effect immediately after a page refresh.

\u{201c}

The golden rule of WordPress development: never hardcode manage_options if the page does not manage critical site settings. Use the least privileged capability sufficient for the task. This is the principle of least privilege in action.

Common Menu Creation Mistakes

Duplicate slugs. If two plugins use the same $menu_slug, WordPress adds a suffix -2, -3, etc. to the later registration. This breaks links and current-page checks. Always use your plugin or theme prefix in the slug.

Missing callback. The $callback parameter is mandatory. If you forget to define the callback function, WordPress renders a blank page with no error. Verify the function name matches exactly.

Wrong capability for submenus. If a submenu capability is higher than its parent menu, the submenu simply does not appear. WordPress does not show items the user cannot access.