WordPress add_submenu_page Example: Register an Admin Submenu Safely

Last reviewed: April 28, 2026

Custom admin screens often belong under an existing WordPress menu instead of becoming another top-level navigation item. add_submenu_page() is the right tool for that job, but it is frequently wired up too early, with the wrong capability, or with a slug that becomes difficult to maintain.

This guide shows how to register an admin submenu page safely and render it with a capability check that matches the menu definition.

Register the submenu on admin_menu

<?php
add_action( 'admin_menu', 'vulnwp_register_reports_submenu' );

function vulnwp_register_reports_submenu() {
	add_submenu_page(
		'tools.php',
		'Security Reports',
		'Security Reports',
		'manage_options',
		'vulnwp-security-reports',
		'vulnwp_render_reports_page'
	);
}

Hooking into admin_menu is important here. Registering earlier can lead to the classic permission error screen even when the capability itself is correct.

Re-check permissions inside the render callback

function vulnwp_render_reports_page() {
	if ( ! current_user_can( 'manage_options' ) ) {
		wp_die( esc_html__( 'You do not have permission to access this page.', 'vulnwp' ) );
	}
	?>
	<div class="wrap">
		<h1>Security Reports</h1>
		<p>Review recent plugin alerts and export status here.</p>
	</div>
	<?php
}

The menu capability controls visibility, but the page callback still needs its own authorization check.

Use a stable menu slug

Keep the menu slug short, unique, and predictable. Avoid using file paths or values tied to a local directory structure. A stable slug makes links, redirects, and support workflows much cleaner.

Submenu pages work well for plugin settings, reports, and tools

Use submenus when the screen belongs inside a broader admin area such as Tools, Settings, or a custom post type. That usually produces a better editorial flow than scattering multiple top-level items across the left navigation.

Production checklist

• Register the submenu on admin_menu.
• Match the capability to the real audience for the screen.
• Perform a second current_user_can() check inside the callback.
• Use a stable, sanitized menu slug.
• Place the screen under the admin section that matches its purpose.
• Test the page with both admin and non-admin accounts.

Common mistakes

• Hooking too early. WordPress can show a permission error even though the capability looks correct.
• Skipping the callback permission check. Visibility alone is not enough for admin safety.
• Using a sloppy slug. File-based or inconsistent slugs create maintenance noise.
• Choosing an overly broad capability. That exposes screens to the wrong role set.
• Adding a top-level menu when the screen clearly belongs under Settings or Tools. Admin UX becomes harder to scan.

Related reading

If the submenu page stores configuration, combine it with the add_settings_error article. If it handles a custom admin form submission, pair it with the admin_post guide.

References and further reading

• WordPress Code Reference: add_submenu_page()
• WordPress Plugin Handbook: Sub-Menus
• WordPress Code Reference: admin_menu