Using WordPress ‘add_theme_page()’ PHP function

by

The add_theme_page() WordPress PHP function is used to add a submenu page to the Appearance main menu in the WordPress dashboard.

Usage

Here’s a basic usage of add_theme_page():

add_theme_page( 'Custom Theme Settings', 'Custom Settings', 'edit_theme_options', 'custom-theme-settings', 'display_custom_settings_page' );

function display_custom_settings_page() {
    echo 'Welcome to the custom settings page!';
}

In this example, a new submenu page titled “Custom Settings” will be added to the Appearance menu. The display_custom_settings_page function will output “Welcome to the custom settings page!” when the page is visited.

Parameters

  • $page_title (string) – The text to be displayed in the title tags of the page when the menu is selected.
  • $menu_title (string) – The text to be used for the menu.
  • $capability (string) – The capability required for this menu to be displayed to the user.
  • $menu_slug (string) – The slug name to refer to this menu by (should be unique for this menu).
  • $callback (callable) – The function to be called to output the content for this page (optional).
  • $position (int) – The position in the menu order this item should appear (optional).

More information

See WordPress Developer Resources: add_theme_page()
Please note, add_theme_page() must be called early, so it’s recommended to use it within the admin_menu hook.

Examples

Basic Usage

// Hooking up our function to WordPress admin_menu action hook.
add_action( 'admin_menu', 'add_custom_theme_page' );

function add_custom_theme_page() {
    add_theme_page( 'Custom Theme Page', 'Custom Page', 'edit_theme_options', 'custom-theme-page', 'display_custom_theme_page' );
}

function display_custom_theme_page() {
    echo 'Welcome to the custom theme page!';
}

In this example, a new submenu page titled “Custom Page” is added to the Appearance menu. The display_custom_theme_page function will output “Welcome to the custom theme page!” when the page is visited.

Display HTML Content

add_action( 'admin_menu', 'add_my_theme_page' );

function add_my_theme_page() {
    add_theme_page( 'My Theme Page', 'My Page', 'edit_theme_options', 'my-theme-page', 'display_my_theme_page' );
}

function display_my_theme_page() {
    echo '<h1>Welcome to my theme page!</h1>';
    echo '<p>This is a paragraph of text.</p>';
}

This example is similar to the first, but the output content includes HTML elements.

Add Theme Page at Specific Position

add_action( 'admin_menu', 'add_theme_page_at_position' );

function add_theme_page_at_position() {
    add_theme_page( 'New Theme Page', 'New Page', 'edit_theme_options', 'new-theme-page', 'display_new_theme_page', 61 );
}

function display_new_theme_page() {
    echo 'Welcome to the new theme page!';
}

In this example, the new submenu page will appear at position 61 in the menu order.

Check User Capability

add_action( 'admin_menu', 'add_theme_page_with_capability' );

function add_theme_page_with_capability() {
    if ( current_user_can( 'edit_posts' ) ) {
        add_theme_page( 'Editor Theme Page', 'Editor Page', 'edit_posts', 'editor-theme-page', 'display_editor_theme_page' );
    }
}

function display_editor_theme_page() {
    echo 'Welcome to the editor theme page!';
}

In this example, the new submenu page will only be added if the current user has the ‘edit_posts’ capability.

Custom Page with Form

add_action( 'admin_menu', 'add_custom_form_theme_page' );

function add_custom_form_theme_page() {
    add_theme_page( 'Form Theme Page', 'Form Page', 'edit_theme_options', 'form-theme-page', 'display_form_theme_page' );
}

function display_form_theme_page() {
    echo '<h1>Submit Your Details</h1>';
    echo '<form method="post">
            <label for="name">Name:</label>
            <input type="text" id="name" name="name">
            <input type="submit" value="Submit">
          </form>';
}

This example adds a new submenu page which contains a simple form for submitting details.