How To Create WordPress Custom Admin Page and Menu From Scratch: Ultimate Guide (Updated)

6 min readDec 10, 2022

WordPress is one of the most popular CMSs for developers, which has many customization and flexibility features, including the expansion of the WordPress admin area. Custom Admin Menu and Page in WordPress is an option to create a custom admin menu with a content page for your own plugin or your theme.

Visit our WordPress Plugin Development Tutorial

Sometimes your WordPress plugin needs an admin menu in the Dashboard for itself to display some reports or settings page. To do this should create the custom Admin Menu and Admin Pages to expand WordPress. Creating an admin menu and admin page is not hard. Follow this tutorial to learn how to create a custom admin page and menu in WordPress CMS.

In this short tutorial, we’ll take a look at the full guide on how to add a custom admin page and its menu to the Dashboard of WordPress from scratch without any plugins.

And be familiar with the following items

Familiar with WordPress plugin development
PHP development
HTML
CSS
Interact WordPress database
Data Sanitization and Validation in WordPress

If you are not familiar with the above items, do not worry, we will explain them all as simple as possible.

What are WordPress Custom Admin Menu and Pages?

After logging in to the admin Dashboard you can see the menu on the left side and the RTL websites on the right side. This menu contains some basic menus like Appearance, Plugins, Settings, Users, etc.

After activating a theme or plugin, the number of menus may increase, the new menu may include the plugin settings page, theme control panel, or any other menu. Custom Admin Menu and Page is a feature that allows WordPress developers to expand the WordPress admin area to suit their needs.

There are two types of menu entries: Top-level and sub-level.

1- The Parts of an Admin Menu & Pages

A menu entry — top-level or sub-level
The page content
Processing logic for forms — if needed

2- Top-Level and Sub-Level Menus

Top-level Admin menus are menus you can see in the sidebar of the Dashboard like “Media”, “Comments” etc. Sub-level menus can find them in the Top-level menus inside, like “Settings -> Reading”. “Reading” is a sub-level menu of “Settings” while “Settings” is a top-level menu.

How to create a custom WordPress Admin Menu and Page

The first step is creating an admin menu. We can do that via add_menu_page or add_submenu_page. We also can use shortcuts of them as add_dashboard_page or add_options_page.

1- How to create a Top Level Admin Page and Menu

The first step is to create a menu entry. To add the admin menu we use the add_menu_page function that we introduce to WordPress, the menu, and then the call back function to manage the admin page content.

The following code describes the menu for WordPress.

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

Open the functions.php file of your theme or add it to your plugin. To do this we create a function hs_admin_menu to define the menu.

function hs_admin_menu() {
    add_menu_page(
        __( 'Page Title', 'my-textdomain' ),
        __( 'Menu Title', 'my-textdomain' ),
        'manage_options',
        'sample-page',
        'hs_admin_page_contents',
        'dashicons-schedule',
        3
    );
}
add_action( 'admin_menu', 'hs_admin_menu' );

The next step is to create some content. All you need to do is create the function defined in argument five and display some content. To add the function to WordPress, we use an action named admin_menu.

function hs_admin_page_contents() {
    ?>
    <h1>
        <?php esc_html_e( 'Welcome to my custom admin page.', 'my-plugin-textdomain' ); ?>
    </h1>
    <?php
}

2- How to Add Sub Menu and Sub Level Page

We may want to create a custom WordPress admin sub-level menu for our own top level. Now we are going to add a submenu to that menu.

The submenu structure will be like the following.

add_submenu_page( 
    string $parent_slug, 
    string $page_title, 
    string $menu_title, 
    string $capability, 
    string $menu_slug, 
    callable $function = '' );

Put the following sub-menu code inside the hs_admin_menu function next to add_admin_menu.

add_submenu_page( 'sample-page',
    __( 'Page Title - Honar Systems', 'my-textdomain' ),
    __( 'Sub Menu Title', 'my-textdomain' ),
    'manage_options',
    'sample-page-sub-menu',
    'hs_sub_menu_admin_page_contents');

And again, like the menu page, add the function below to display sub-menu page content.

function hs_sub_menu_admin_page_contents(){
    ?>
    <h1>
        <?php esc_html_e( 'Welcome to my custom sub menu admin page.', 'my-plugin-textdomain' ); ?>
    </h1>
    <?php
}

If you are developing a custom plugin you can use your plugin address as a parent “slug” like the below code.

add_submenu_page(
   'myplugin/myplugin-admin-page.php',
    __('Page Title - Honar Systems', 'my-textdomain'),
    __('Sub Menu Title', 'my-textdomain'),
    'manage_options',
    'myplugin/myplugin-admin-sub-page.php',
    'hs_sub_menu_admin_page_contents' );

You should know that it is possible to add a submenu to existing menus. WordPress basic top-level menus have their own functions to add sub-level menus.

add_posts_page Adds a submenu under the Posts menu
add_pages_page Adds a submenu under the Pages menu
add_media_page Adds a submenu under the Media menu
add_comments_page Adds a submenu under the Comments menu
add_theme_page Adds a submenu under the Appearance menu
add_plugin_page Adds a submenu under the Plugins menu
add_users_page Adds a submenu under the Users menu
add_management_page Adds a submenu under the Tools menu
add_options_page Adds a submenu under the Settings menu

If you don’t need the top-level menu, we recommend you add it to the sub-menu. Too many plugins add top-level entries, which end up polluting the admin heavily.

Adding Custom CSS and JS Files in WordPress Admin Pages and Menus

Sometimes we need to use our own style for our custom admin pages and menus. To do this we need to add our styles and js codes by the hook.

Following codes, add our own style, WordPress color picker style, and our own JavaScript code.

We create a folder and name it assets in the theme or plugin folder. Insert style and js file inside it.

function hs_load_custom_wp_admin_style($hook)
{
    wp_enqueue_style('custom_wp_admin_css', get_template_directory_uri() . '/assets/style.css');
    // Load color picker styles.
    wp_enqueue_style('wp-color-picker');
    wp_enqueue_script('custom_wp_admin_js', get_template_directory_uri() . '/assets/script.js');
}
add_action('admin_enqueue_scripts', 'hs_load_custom_wp_admin_style');

In the above code, the wp-color-picker is the WordPress build-in style and we consider that we writing our code inside the functions.php file. Otherwise, the above addresses should be changed to the existing address.

Final Code

The final code will be like the following.

function my_admin_menu()
{
    add_menu_page(
        __('Page Title - Honar Systems', 'my-textdomain'),
        __('Menu Title', 'my-textdomain'),
        'manage_options',
        'sample-page',
        'my_admin_page_contents',
        'dashicons-schedule',
        3
    );
add_submenu_page('sample-page',
        __('Page Title - Honar Systems', 'my-textdomain'),
        __('Sub Menu Title', 'my-textdomain'),
        'manage_options',
        'sample-page-sub-menu',
        'my_sub_menu_admin_page_contents');
}
add_action('admin_menu', 'my_admin_menu');
function my_admin_page_contents()
{
    ?>
    <h1>
        <?php esc_html_e('Welcome to my custom admin page.', 'my-plugin-textdomain'); ?>
    </h1>
    <?php
}
function my_sub_menu_admin_page_contents()
{
    ?>
    <h1>
        <?php esc_html_e('Welcome to my custom sub menu admin page.', 'my-plugin-textdomain'); ?>
    </h1>
    <?php
}
function load_custom_wp_admin_style($hook)
{
    wp_enqueue_style('custom_wp_admin_css', get_template_directory_uri() . '/assets/style.css');
    // Load color picker styles.
    wp_enqueue_style('wp-color-picker');
    wp_enqueue_script('custom_wp_admin_js', get_template_directory_uri() . '/assets/script.js');
}
add_action('admin_enqueue_scripts', 'load_custom_wp_admin_style');

How to Create WordPress custom admin page without a menu (hidden menu)

Admin pages are often used for plugin or theme settings, and sometimes for the user guide. However, there are situations you want to add a hidden admin page that only shows under a specific condition, and won’t show in the admin menu. Pages such as WordPress welcome page, and credit page for new versions are examples. These pages are displayed only once when users update their WordPress websites and they contain only information about the new versions.

To hide the Admin Page menu, remove the admin menu on admin_head hook. The code is as simple as follows:

add_action( 'admin_head', function() {
    remove_submenu_page( 'index.php', 'hidden-page-menu' );
} );

The definition of a hidden sub-menu is exactly like a normal sub-menu in items, but the value of items has a little bit different. Alternatively, you can register and hide the admin page at the same time by setting the parent_slug parameter to null in the function add_submenu_page, like this:

add_submenu_page(
    'null',
    __('Hidden Menu - Honar Systems', 'my-textdomain'),
    __('Hidden', 'my-textdomain'),
    'manage_options',
    'hidden-page-sub-menu',
    'my_hidden_sub_menu_admin_page_contents'
);

As you can see, the parent slug is null. It means that this sub-menu belongs to no item. But if you go URL below you can see your content.

admin.php?page=hidden-page-sub-menu

More details: https://honarsystems.com/wordpress-custom-admin-page/