Sub-Menus

Add a Sub-Menu Add a Sub-Menu

To add a new Sub-menu to WordPress Administration, use the add_submenu_page() function.

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

Example Example

Lets say we want to add a Sub-menu “WPOrg Options” to the “Tools” Top-level menu.

The first step will be creating a function which will output the HTML. In this function we will perform the necessary security checks and render the options we’ve registered using the Settings API.

Note: We recommend wrapping your HTML using a <div> with a class of wrap.
function wporg_options_page_html()
{
	// check user capabilities
	if (!current_user_can('manage_options')) {
		return;
	}
	?>
	<div class="wrap">
		<h1><?= esc_html(get_admin_page_title()); ?></h1>
		<form action="options.php" method="post">
			<?php
			// output security fields for the registered setting "wporg_options"
			settings_fields('wporg_options');
			// output setting sections and their fields
			// (sections are registered for "wporg", each field is registered to a specific section)
			do_settings_sections('wporg');
			// output save settings button
			submit_button('Save Settings');
			?>
		</form>
	</div>
	<?php
}

The second step will be registering our WPOrg Options Sub-menu. The registration needs to occur during the admin_menu action hook.

function wporg_options_page()
{
	add_submenu_page(
		'tools.php',
		'WPOrg Options',
		'WPOrg Options',
		'manage_options',
		'wporg',
		'wporg_options_page_html'
	);
}
add_action('admin_menu', 'wporg_options_page');

For a list of parameters and what each do please see the add_submenu_page() in the reference.

Top ↑

Predefined Sub-Menus Predefined Sub-Menus

Wouldn’t it be nice if we had helper functions that define the $parent_slug for WordPress built-in Top-level menus and save us from manually searching it through the source code?

Below is a list of parent slugs and their helper functions:

Top ↑

Remove a Sub-Menu Remove a Sub-Menu

The process of removing Sub-menus is exactly the same as removing Top-level menus.

Top ↑

Submitting forms Submitting forms

The process of handling form submissions within Sub-menus is exactly the same as Submitting forms within Top-Level Menus.

add_submenu_page() along with all functions for pre-defined sub-menus (add_dashboard_page, add_posts_page, etc.) will return a $hookname, which you can use as the first parameter of add_action in order to handle the submission of forms within custom pages:

function wporg_options_page() {
	$hookname = add_submenu_page(
		'tools.php',
		'WPOrg Options',
		'WPOrg Options',
		'manage_options',
		'wporg',
		'wporg_options_page_html'
	);

	add_action( 'load-' . $hookname, 'wporg_options_page_html_submit' );
}

add_action('admin_menu', 'wporg_options_page');

As always, do not forget to check whether the form is being submitted, do CSRF verification, validation, and sanitization.