What is the add_submenu_page() Function

If you’re using WordPress, you must be familiar with the menus on the left panel of the admin dashboard. When you hover on some of the options, you will see their submenus that serve as shortcuts to the settings you frequently access.

Should you need more shortcuts, you can add custom submenus by using the add_submenu_page() function. For instance, inserting a Team Profile page below the Users menu. 

The function also allows developers of plugins, themes, or child themes to create their own setting pages under the top-level menus. As an example, you can find Akismet’s configurations menu under the WordPress Settings page:

The syntax for this WordPress function is: 

add_submenu_page( string $parent_slug, string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = ”, int $position = null )

With the parameters:

• $parent_slug — the slug of the parent menu.
• $page_title — refers to the title when you open the submenu page.
• $menu_title — the display name of the submenu on the dashboard.
• $capability — defines what permission users must have to see the submenu. 
• $menu_slug — a unique slug name for the submenu. Use only lowercase alphanumeric, dashes, and underscore characters.
• $function — a callback function to show the content of the page. The default value is “.
• $position — the submenu’s position in the menu order. null is the default value.

How to Add a Submenu to the Navigation Bar with add_submenu_page()

In this tutorial, you’ll be applying the function on your WordPress theme.

Before that, make sure you have a child theme ready as you’ll be editing your WordPress theme’s functions.php file. It’s to make sure the main theme file is untouched if you mess up your edits. Follow the tutorial on this article to create one.

Once you’re all set, proceed with the following steps:

1. Go to File Manager from your hPanel, then navigate to public_html -> wp-content -> themes folder.
2. Select your child theme folder and double click on the functions.php file. 
3. Insert the following code before the closing tag ?> to add a submenu under the Posts menu:
   add_action('admin_menu', 'register_my_custom_submenu_page');

function register_my_custom_submenu_page() {
add_submenu_page(
'edit.php',
'Submenu Page',
'My Custom Submenu Page',
'manage_options',
'my-custom-submenu-page',
'my_custom_submenu_page_content',
'Null' );

}
function my_custom_submenu_page_content() {
echo '<div class="wrap">';
echo '<h2>Submenu Page</h2>';
echo '</div>';

4. Press Save & Close, and acess your WordPress Dashboard. You will see there’s a new submenu under the Posts options.

You can add the submenu to a different parent menu such as the Users and Tools with the slug users.php and tools.php, respectively. Feel free to change the parent slug based on your needs. 

Wrapping Up

The add_submenu_page() function is very useful if you want to have a custom WordPress submenu under a top-level menu. It can also be utilized to make setting pages for self-made plugins and themes.

To apply the function on your theme, simply insert the code given on the tutorial above to the theme’s functions.php file. Use a child theme to avoid messing up the main code.

Adding a custom submenu is quite straightforward, so why not give it a try?