How to Add a Custom Menu in the WordPress Admin Dashboard: A Step-by-Step Guide

Adding a custom menu in the WordPress admin dashboard can greatly enhance your workflow, especially if you’re developing a custom plugin or theme. Custom menus in the admin panel allow you to organize functionality, make user navigation easier, and group relevant settings for administrators or editors.

In this tutorial, we’ll go over how to create a simple custom menu in the WordPress admin dashboard using code. This guide assumes you have basic knowledge of PHP and WordPress development.

Step 1: Set Up a Function to Create the Menu

WordPress provides a built-in function, add_menu_page(), to add custom menus to the admin dashboard. To start, you need to create a function that will register the menu with WordPress.

Here’s a basic structure of the function that will handle the menu creation:

function my_custom_admin_menu() {
    add_menu_page(
        'Custom Menu Title',       // Page Title
        'Custom Menu',             // Menu Title
        'manage_options',          // Capability required to access the menu
        'my-custom-menu',          // Menu Slug
        'my_custom_menu_page',     // Callback function to display the content of the menu page
        'dashicons-admin-generic', // Icon URL or dashicons class for the menu
        6                          // Position of the menu
    );
}

In this function:

• Page Title: This is the title of the menu page, displayed in the browser’s title bar.
• Menu Title: This is the title that will be displayed in the WordPress admin menu.
• Capability: Only users with this capability will see the menu. In this case, manage_options limits it to administrators.
• Menu Slug: A unique identifier for the menu.
• Callback Function: The function that will render the content of the menu page.
• Icon: You can use a custom image URL or a Dashicons class.
• Position: Specifies where in the menu the new item will appear.

Step 2: Add the Function to the WordPress Hook

To ensure WordPress knows when to add the custom menu, we need to hook our function into the admin_menu action. This will trigger the function when the admin dashboard is loaded.

add_action('admin_menu', 'my_custom_admin_menu');

This tells WordPress to execute the my_custom_admin_menu function when it loads the admin menu.

Step 3: Create the Callback Function to Display Page Content

Now, we need to define the my_custom_menu_page() function to output content for the custom menu page. This is where you can add your HTML, forms, or any PHP logic to customize what gets displayed.

function my_custom_menu_page() {
    echo '<div class="wrap">';
    echo '<h1>Welcome to My Custom Admin Menu</h1>';
    echo '<p>This is where you can add custom functionality or settings.</p>';
    echo '</div>';
}

You can modify this function to output whatever content you need, such as forms, reports, or anything else relevant to your custom menu.

Step 4: Add Submenus (Optional)

If you want to add submenus to your custom menu, you can use the add_submenu_page() function. This can be helpful when you want to group related functionality under one main menu item.

Here’s how you add a submenu:

function my_custom_admin_menu() {
    add_menu_page(
        'Custom Menu Title', 
        'Custom Menu', 
        'manage_options', 
        'my-custom-menu', 
        'my_custom_menu_page', 
        'dashicons-admin-generic', 
        6
    );

    add_submenu_page(
        'my-custom-menu',       // Parent menu slug
        'Submenu Page Title',   // Page title
        'Submenu',              // Menu title
        'manage_options',       // Capability
        'my-submenu-slug',      // Submenu slug
        'my_custom_submenu_page'// Callback function
    );
}

function my_custom_submenu_page() {
    echo '<div class="wrap">';
    echo '<h1>Welcome to My Custom Submenu Page</h1>';
    echo '<p>This is the submenu content area.</p>';
    echo '</div>';
}

The add_submenu_page() function adds a submenu under the main custom menu. It takes similar parameters to add_menu_page() but includes the parent menu slug as the first argument.

Step 5: Testing Your Custom Menu

After adding the above code to your plugin file or theme’s functions.php, you should see a new custom menu in the admin dashboard.

1. Log into the WordPress Admin Dashboard.
2. Locate Your Custom Menu in the sidebar (usually at the bottom or based on the position you specified).
3. Click the Menu, and you should see the content you added in your callback function displayed on the page.

Additional Customization

• Icon Customization: You can replace the dashicon with a custom icon by passing the URL to the image file as the sixth argument in the add_menu_page() function.
• Permissions: Modify the manage_options capability if you want other user roles to access the menu (e.g., edit_posts for editors).
• Positioning: Adjust the position by changing the number in the last argument of add_menu_page().

Conclusion

Adding a custom menu to the WordPress admin dashboard is a powerful way to integrate your plugin or theme features into WordPress. This feature allows developers to enhance the functionality of WordPress for both admins and editors, providing a more personalized experience. Once you’ve mastered the basics, you can further explore adding settings, forms, and even external API integrations to your custom admin menus.

Feel free to experiment and extend this approach to suit your specific needs!