How To Create WordPress Custom Admin Page and Menu: Full Guide

WordPress is one of the most popular CMSs for developers and webmasters, 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 like with the add_menu_page built-in function.

A custom admin page is a page that you can create and manage by the WordPress administrator. It can be used for a variety of purposes, such as displaying information, creating forms, or managing content. Custom admin pages allow users to customize their WordPress experience to fit their needs.

Sometimes your custom WordPress plugin needs an admin menu in the Dashboard itself to display some reports, a settings page, or even a custom Dashboard widget. To do this you should create the custom Admin Menu and Admin Pages to expand the WordPress admin area. Creating an admin menu and admin page is easy. Follow this tutorial to learn how to create a custom admin page and menu in WordPress CMS without a plugin.

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. In this tutorial to better understand, create, and implement the Custom Admin Menu and its Page in WordPress, you should have prepared the following items.

• Local development environment or WordPress website
• Installed WordPress and ready to be used for installing a plugin

And be familiar with the following items

• Familiar with WordPress plugin development
• PHP development
• HTML
• JavaScript
• 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 simply as possible.

What are WordPress Custom Admin Menu and Page?

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 create and expand the WordPress admin area to suit their needs.

There are two types of admin menu entries: Top-level and sub-level. If users need to interact with your plugin daily you can use a top-level entry. If your admin page is just for settings, a sub-level entry in the “Settings” top-level menu is more appropriate.

To deal with the client-side menu (user menu), read our tutorial about WordPress custom menus.

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

WordPress Top-level Admin menu is a menu 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 as add_dashboard_page or add_options_page.

To add a custom admin menu and its content page in WordPress, we need two things:

• An admin menu (add_menu_page function)
• Page Content

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

To create a custom WordPress top-level Admin Page and Menu we have to create a menu entry at first. 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 )

The WordPress built-in add_menu_page function takes seven arguments.

• page_title (Required) The text is to be displayed in the title tags of the page when the menu is selected.
• menu_title (Required) is the title that shows up in the menu.
• capability (Required) The capability required for this menu to be displayed to the user. For example, if it contains some general options for the site, manage_option could be the best choice. This can be used to restrict it to only admins, editors, or authors. Just set it carefully to avoid any possible security issues.
• menu_slug (Required) The slug name that refers to this menu. It should be unique for this menu page. This will be used as a parameter in the URL of your custom admin page.
• function (Optional) The function to be called to show the output content for this page.
• icon_url (Optional) The URL of the icon to be used for this menu. You can use an image, encoded SVG, or dash icons.
  • In order to use an image, simply pass the URL of the image.
  • Using existing WordPress icons.
  • You can use none value to leave div.wp-menu-image empty, so an icon can be added via CSS.
  • You can use the SVG file. Convert the SVG file to base64 and add it with data:image/svg+xml;base64code.
• position (Optional) The position in the menu order should appear. Here is the list of numbers of default admin menus:
  • 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

Open the functions.php file of your theme or add the add_menu_page to your WordPress 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
}

As you see, the page title, menu title, menu icon, and end of the URL are items that are introduced.

2- How to Add Sub Menu and Sub Level Page

We added a top-level menu (add_menu_page) to the WordPress Dashboard. We may want to create a custom WordPress admin sub-level menu and its page 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 create and add an admin submenu and its page to the existing WordPress built-in menu. 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

For example, adding a submenu to the Comments top-level menu.

add_comments_page( 
    $page_title, 
    $menu_title, 
    $capability, 
    $menu_slug, 
    $function);

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.

Create and Add Custom CSS and JS Files in the WordPress Admin Page and Menu

Sometimes we need to use our own style for our WordPress custom admin page and menu. 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.

• How to Include Properly CSS and JS Files in WordPress

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.

Load Styles Only on a Specific Page

If you add your styles like the previous section, you can see your style changing the whole admin panel’s style. To prevent that, we have to check if the current page is our page or not. Then we have to check our hook, like below. Our main menu hook will be toplevel_page_sample-page.

function hs_load_custom_wp_admin_style($hook) {
    // Load only on ?page=sample-page not in sub menu
    if( $hook != 'toplevel_page_sample-page') {
        return;
    }
    wp_enqueue_style( 'custom_wp_admin_css', get_template_directory_uri().'/assets/style.css' );
}
add_action( 'admin_enqueue_scripts', 'hs_load_custom_wp_admin_style' );

How to find our custom admin page’s hook? The answer is below the code. This code will display the current page’s hook.

function hs_load_custom_wp_admin_style( $hook ) {
    wp_die( $hook );
}
add_action( 'admin_enqueue_scripts', 'hs_load_custom_wp_admin_style' );

Final Code

The final code to create a custom WordPress admin page and menu 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)

The admin page is often used for a WordPress 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 the WordPress 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 admin sub-menu is exactly like a normal WordPress sub-menu in items, but the value of items is 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 WordPress built-in 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