Top-Level Menus

Add a Top-Level Menu Add a Top-Level Menu

To add a new Top-level menu to WordPress Administration, use the add_menu_page() function.

<?php
add_menu_page(
    string $page_title,
    string $menu_title,
    string $capability,
    string $menu_slug,
    callable $function = '',
    string $icon_url = '',
    int $position = null
);

Example Example

Lets say we want to add a new Top-level menu called “WPOrg”.

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.

<?php
function wporg_options_page_html() {
    // check user capabilities
    if ( ! current_user_can( 'manage_options' ) ) {
        return;
    }
    ?>
    <div class="wrap">
      <h1><?php 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 menu. The registration needs to occur during the admin_menu action hook.

<?php
function wporg_options_page() {
    add_menu_page(
        'WPOrg',
        'WPOrg Options',
        'manage_options',
        'wporg',
        'wporg_options_page_html',
        plugin_dir_url(__FILE__) . 'images/icon_wporg.png',
        20
    );
}
add_action( 'admin_menu', 'wporg_options_page' );

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

Top ↑

Using a PHP File for HTML Using a PHP File for HTML

The best practice for portable code would be to create a Callback that requires/includes your PHP file.

For the sake of completeness and helping you understand legacy code, we will show another way: passing a PHP file path as the $menu_slug parameter with an null $function parameter.

<?php
function wporg_options_page() {
    add_menu_page(
        'WPOrg',
        'WPOrg Options',
        'manage_options',
        plugin_dir_path(__FILE__) . 'admin/view.php',
        null,
        plugin_dir_url(__FILE__) . 'images/icon_wporg.png',
        20
    );
}
add_action( 'admin_menu', 'wporg_options_page' );

Top ↑

Remove a Top-Level Menu Remove a Top-Level Menu

To remove a registered menu from WordPress Administration, use the remove_menu_page() function.

<?php
remove_menu_page(
    string $menu_slug
);

Warning:
Removing menus won’t prevent users accessing them directly.
This should never be used as a way to restrict user capabilities.

Top ↑

Example Example

Lets say we want to remove the “Tools” menu from.

<?php
function wporg_remove_options_page() {
    remove_menu_page( 'tools.php' );
}
add_action( 'admin_menu', 'wporg_remove_options_page', 99 );

Make sure that the menu have been registered with the admin_menu hook before attempting to remove, specify a higher priority number for add_action().