Developer · Guide
How to Add a Custom Admin Page

Short answer
To add a custom admin page, hook a function to admin_menu and call add_menu_page() inside it with a page title, menu title, capability, slug, callback, icon, and position. Check the capability again inside the callback with current_user_can(), since the menu only hides the link. Use a sub-page under Settings or Tools when one screen is enough, and save top-level menus for plugins with several related screens.
Key takeaways
- add_menu_page() adds a top-level menu page, and it takes 7 parameters in a set order.
- Always hook the menu code to admin_menu, or the page will not register.
- Check the capability in the callback, since the menu only hides the link.
- Use a sub-page under Settings or Tools for a single screen.
- Since WordPress 4.4, position numbers do not need to be unique.
What is a custom admin page in WordPress?
A custom admin page is a screen you add to the WordPress dashboard to show settings or tools for your plugin or theme.
It lives inside wp-admin, next to Posts, Pages, and Settings. Only users with the capability you set can see it in the menu and open it. A plugin for bookings might add a page that lists bookings, while a theme might add a page with its own settings.
The Theme Handbook states that a theme author may need a settings screen so users can change how the theme works, and the best way to give them one is an administration menu item (checked November 2026).
That item is the door to your page. The page itself is the HTML your callback function prints when a user opens it.
You add the page with code, not with a dashboard switch. The code runs from a small custom plugin or from a child theme, and it uses three functions you will meet below: add_action(), add_menu_page(), and your own callback.
When should you add a top-level page instead of a sub-page?
Add a top-level page only when your plugin or theme needs several related screens of its own.
The Theme Handbook states that it is rare for a theme to need a new top-level menu, and that a top-level menu fits only when the theme brings a whole new concept with many screens (checked November 2026).
Job boards and conference tools are the handbook's examples of that case. Most plugins and themes do not meet that bar.
Use a sub-page under an existing menu in all other cases. A settings screen belongs under Settings, a report belongs under Tools, and a list of items belongs under the menu for that item type.
The WordPress Codex gives the same three steps for admin menus and lists the same menu functions, including add_menu_page() and add_submenu_page() (checked November 2026).
The Theme Handbook lists the top-level menus you can attach to, with Settings at position 80, Tools at 75, and Appearance at 60 (checked November 2026).
Those numbers show the order of the menu, and they help you pick the right parent. A single screen never needs a top-level menu of its own.
What does add_menu_page() do?
add_menu_page() adds a top-level menu page to the WordPress admin sidebar.
Developer.WordPress.org states that the function takes a capability, which decides whether the menu shows for a user, and that the callback hooked to the page must also check that capability (checked November 2026).
That double check matters: the menu hides from users without the right role, and the callback blocks them even if they guess the URL.
The function takes 7 parameters in this order: page title, menu title, capability, menu slug, callback, icon URL, and position. The first 4 are required, and the last 3 are optional.
The page title shows in the browser tab, the menu title shows in the sidebar, and the slug is the unique name for the page in its URL.
Developer.WordPress.org states that add_menu_page() was introduced in WordPress 1.5.0 and returns the page hook suffix as a string (checked November 2026).
That hook suffix is useful later, since you can use it to load scripts or styles only on your page.
How do you add a top-level admin page with code?
Add a top-level admin page by hooking a function to admin_menu and calling add_menu_page() inside it.
The Theme Handbook states that adding a menu takes three steps: write a function with the menu code, register that function on the admin_menu hook, and write the HTML output for the screen (checked November 2026).
It also warns that many developers skip the second step, but the menu code must sit inside a function that is registered on the hook.
Here is a short, working example:
add_action( 'admin_menu', 'acme_add_admin_page' );
function acme_add_admin_page() {
add_menu_page(
'Acme Reports',
'Acme Reports',
'manage_options',
'acme-reports',
'acme_reports_page',
'dashicons-chart-pie',
30
);
}
function acme_reports_page() {
if ( ! current_user_can( 'manage_options' ) ) {
wp_die( 'You do not have sufficient permissions to access this page.' );
}
echo 'Your report goes here.';
}
Add your own markup inside the callback, such as a div with the class wrap and a heading for the page title.
Put this code in a small custom plugin or in a child theme's functions.php file. A guide on theme vs plugin in WordPress helps you pick which home fits your code. Use manage_options when only admins should see the page, since that capability belongs to the Administrator role.
What do the position numbers mean?
Position numbers set where your menu item sits in the admin sidebar, with lower numbers near the top.
Developer.WordPress.org lists the core positions: Dashboard at 2, Posts at 5, Media at 10, Pages at 20, Comments at 25, Appearance at 60, Plugins at 65, Users at 70, Tools at 75, and Settings at 80 (checked November 2026).
A position of 30 would sit your item between Comments and Appearance, while a position of 90 would sit it below Settings.
Developer.WordPress.org states that since WordPress 4.4, you do not need a unique position number to avoid conflicts (checked November 2026).
WordPress shifts items that share a number by a small amount, so two plugins can both ask for 30 without breaking the menu.
Leave the position blank when you have no strong reason to pick one. WordPress then puts your item at the bottom of the menu. Pick a number only when the item must sit near related screens, such as a report page near Tools.
How do you add a sub-page under an existing menu?
Add a sub-page with add_submenu_page(), using the parent menu slug as its first parameter.
The Theme Handbook states that the parent slug is the file name of the standard admin screen for that menu, such as options-general.php for Settings and tools.php for Tools (checked November 2026).
For your own top-level menu, the parent slug is the slug you gave it in add_menu_page().
The Plugin Handbook lists wrapper functions for common parents, such as add_options_page() for Settings and add_management_page() for Tools (checked November 2026).
These wrappers take the same page title, menu title, capability, slug, and callback, but they fix the parent for you.
Here is a sub-page under Settings:
add_action( 'admin_menu', 'acme_add_settings_page' );
function acme_add_settings_page() {
add_options_page(
'Acme Settings',
'Acme Settings',
'manage_options',
'acme-settings',
'acme_settings_page'
);
}
function acme_settings_page() {
if ( ! current_user_can( 'manage_options' ) ) {
wp_die( 'You do not have sufficient permissions to access this page.' );
}
echo 'Your settings form goes here.';
}
Add your settings fields inside the callback, inside a div with the class wrap.
The page then opens at admin.php?page=acme-settings from the Settings menu. Use the same pattern for Tools with add_management_page(), or for Appearance with add_theme_page().
How do you keep the page safe for other user roles?
Keep the page safe by checking the capability in the callback, not only in the menu call.
Developer.WordPress.org states that the function hooked to handle the page output must check that the user has the required capability as well (checked November 2026).
The menu hides the link from users without that capability, but a direct URL can still reach the page, so the callback is the real guard.
Use current_user_can( 'manage_options' ) at the top of the callback, and stop with wp_die() when the check fails.
The Theme Handbook shows this exact pattern in its example, with the message “You do not have sufficient permissions to access this page.” (checked November 2026). Copy that pattern for every admin page you add.
Pick the weakest capability that still fits the job. Use edit_posts when editors should see the page, and manage_options only when the page changes site-wide settings.
The Plugin Handbook states that current_user_can() is a wrapper for user_can() using the current user, and the Theme Handbook states that user levels are deprecated and should not be used here (checked November 2026). Capabilities are the current way to control access.
The Common APIs Handbook states that the Settings API was added in WordPress 2.7 and lets admin pages with settings forms be managed semi-automatically (checked November 2026).
Make WordPress Core states that register_setting() in WordPress 4.7 accepts an array of arguments, including type and description, for settings saved through that API (checked November 2026).
Learn WordPress states that a settings page on the network admin dashboard uses the network_admin_menu hook, while a page on one site uses admin_menu (checked November 2026).
That hook adds the page to the Network Admin screens, where network settings live.
How do you check that the page works?
Check the page by logging in as an admin, opening it from the menu, and then testing it as a lower role.
First, log in as an administrator and click the new menu item. The page should open, show its title, and print the content your callback outputs. Check the URL: a top-level page opens at admin.php?page=your-slug, where your-slug is the slug you set.
Next, log in as an editor or author and confirm the menu item is hidden. Then try the page URL directly while logged in as that user.
You should see the permissions message, not the page content. If the content shows, your callback check is missing or uses the wrong capability.
Developer.WordPress.org warns that hooking too early causes the “You do not have sufficient permissions to access this page” error, and that the hook you should use is admin_menu (checked November 2026).
If you see that error as an admin, move your code onto admin_menu and check for typos in the slug.
A guide on how to use Site Health in WordPress covers a built-in screen that reports faults on your site, which helps when a new page breaks the dashboard.
A guide on how to set up a staging site for WordPress shows how to test the page where a fault cannot hurt live readers.
What mistakes should you avoid?
Avoid calling add_menu_page() outside a hooked function, because the menu will not register.
The Theme Handbook states that you cannot simply call the menu code, and that you must put it inside a function and register that function on the hook (checked November 2026).
Code that runs too early or at the top level of a file fails in quiet ways, such as a missing menu item or a permissions error.
Avoid adding a top-level menu for a single settings screen. That choice clutters the sidebar and hides your screen from users who look under Settings first. Use a sub-page unless you have several related screens.
Avoid skipping the capability check in the callback. The menu hides the link, but it does not block the URL. Every callback needs its own check, even on pages that seem harmless.
| Function | What it adds | First parameter | When to use it |
|---|---|---|---|
add_menu_page() | Top-level menu page | Page title | Several related screens of your own |
add_submenu_page() | Sub-page under any menu | Parent slug | One screen under a current menu |
add_options_page() | Sub-page under Settings | Page title | Settings only admins should change |
add_management_page() | Sub-page under Tools | Page title | Tools and reports |
add_theme_page() | Sub-page under Appearance | Page title | Theme screens and options |
Frequently asked questions
Where do I put the code for a custom admin page?
Put it in a small custom plugin when the page belongs to a plugin, or in a child theme functions.php file when it belongs to a theme. A custom plugin keeps the page when you change themes, while a child theme keeps it safe from theme updates. Avoid putting it in the parent theme functions.php file, since an update can wipe it out. Keep the code in one place so you can find it later.
What capability should I use for my admin page?
Use the weakest capability that still fits the job. Use manage_options when only admins should see the page, since that capability belongs to the Administrator role. Use edit_posts when editors should see it too. The Settings API needs manage_options, since users without it cannot save options. Never use old user levels, since they are deprecated and should not be used here.
Why do I see a permissions error as an admin?
You hooked the code too early, or you called add_menu_page() outside a hooked function. The code must sit inside a function that is registered on the admin_menu hook, since that hook runs after the basic admin menu is in place. Move your add_menu_page() call into a function hooked to admin_menu. Also check the slug for typos, since a wrong slug breaks the page link.
Can I add a sub-page under my own top-level menu?
Yes. Call add_submenu_page() with your top-level slug as the first parameter, then the page title, menu title, capability, sub-page slug, and callback. The sub-page then opens under your top-level menu. You can add several sub-pages this way, one call per page. Each sub-page still needs its own capability check in its callback, even when it shares the parent menu.
How do I add a settings page for a multisite network?
Hook to network_admin_menu instead of admin_menu, and add the page from a plugin that runs on the network. That hook adds the page to the Network Admin screens, where network settings live. A page hooked only to admin_menu shows on single sites, not in Network Admin. Check the capability in the callback as usual, since network pages need the same guard as single-site pages.
Sources
- add_menu_page() Developer.WordPress.org
- Administration Menus - Theme Handbook Developer.WordPress.org
- Sub-Menus - Plugin Handbook Developer.WordPress.org
- Roles and Capabilities - Plugin Handbook Developer.WordPress.org
- Settings - Common APIs Handbook Developer.WordPress.org
- Administration Menus WordPress Codex
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.


