How to create a WordPress settings page

Do you want to create a custom settings page for your theme or plugin? A settings page allows your users to customize the behavior of your theme or plugin.

Creating a custom settings page in WordPress is much easier than most developers think. It only takes these 3 steps:

Step 1: Register The Settings Page

First, you need to register your settings page using the add_options_page function:

add_options_page( $page_title, $menu_title, $capability, $menu_slug, $callback, $position);

These are the arguments this function takes (in order):

• $page_title — Title of your settings page.
• $menu_title — The title/name of the menu item.
• $capability — The minimum capability a user needs to access this settings page.
• $menu_slug — A unique slug that will be used in the URL to display this page.
• $callback — The function that will render this settings page. (Step 3)
• $position — An integer value for where you want this menu item to be displayed.

This function adds a link to your settings page in the Settings section of your WordPress admin dashboard.

PRO TIP: Skip all these steps and generate the code for your settings page using our free settings page code generator. It offers dozens of customization options. And gives you a quick template to start with.

Here’s what a call to this function looks like:

function wpturbo_register_custom_settings_page() {
    add_options_page( 'My Custom Settings Page', 'Custom Plugin Settings', 'manage_options', 'wpturbo-custom-settings-page', 'wpturbo_render_custom_settings_page', 2 );
}
add_action( 'admin_menu', 'wpturbo_register_custom_settings_page' );

Step 2: Register The Settings Fields

Now that your menu is registered, you need to register your setting fields.

There are three functions you need to register:

• register_setting — This function is used to register an option group and an option name.
• add_settings_section — This function registers a section that will display your settings.
• add_settings_field — This function registers an input field that will be rendered in your selected registered section.

This is what it usually looks like:

function wpturbo_register_settings() {
    register_setting( 'wpturbo_api_settings_options', 'wpturbo_api_settings_options', 'wpturbo_validate_options' );
	
    add_settings_section( 'api_key_settings', 'API Settings', 'wpturbo_render_settings_section', 'wpturbo-custom-settings-page' );

    add_settings_field( 'wpturbo_api_key', 'Your API Key', 'wpturbo_render_api_key_settings_field', 'wpturbo-custom-settings-page', 'api_key_settings' );
}
add_action( 'admin_init', 'wpturbo_register_settings' );

The register_setting function takes these arguments (in order):

• $option_group — A unique name for your options group.
• $option_name — The name of this option that you are registering.
• $args — An array of additional options or a field sanitization function name.

The add_settings_section function takes these arguments (in order):

• $id — A unique ID for this section. Will be used as the CSS ID for this section as well.
• $title — The title of this settings section.
• $callback — The name of the function that will output the header of this section. This is the content before the fields and after the heading of this section.
• $page — The slug of the page where this section will be rendered. Your registered this slug in the first step above.

These are the arguments that the add_settings_field function takes:

• $id — A unique slug ID for this settings field.
• $title — The label for this settings field.
• $callback — The name of the function that will render this field.
• $page — The slug of the options page you registered in step 1.
• $section — The ID of the section you want to render this flied to.
• $args — Additional arguments for this function. Optional.

Step 3: Render The Settings Page, Settings Sections and Fields

Now, you need to render the settings page:

<?php
function wpturbo_render_custom_settings_page() {
    ?>
    <h2>My Custom Plugin Settings Page</h2>
    <form action="options.php" method="post">
        <?php 
        settings_fields( 'wpturbo_api_settings_options' );
        do_settings_sections( 'api_key_settings' ); ?>
        <input name="submit" class="button button-primary" type="submit" value="Save Settings" />
    </form>
    <?php
}

In the above example, the settings_fields function takes the name of the options group you registered with the register_setting function. It doesn’t render the fields. It renders other hidden important fields.

Next, the do_settings_sections function renders the section whose name you pass to it. This function basically calls the renderer function of the section and outputs the heading for the section.

Now that your settings page renderer is ready, you need to create the renderer function for the settings section that you registered:

function wpturbo_render_settings_section(){
	echo "<p>A quick description of this section displayed after the heading and before the fields.</p>"
}

Next, you need a render function for the field that you registered above:

function wpturbo_render_api_key_settings_field() {
	$options = get_option( 'wpturbo_api_settings_options' );
	$api_key = $options['api_key'];
    echo "<input id='wpturbo-api-key-settings-field' name='wpturbo_api_settings_options[api_key]' type='text' value='" . esc_attr( $api_key ) . "' />";
}

The best part of using the WordPress Options Page API is that it automatically stores your registered settings when you use it as the name attribute of a field. In our case, our option is an array. Our field’s name is ‘wpturbo_api_settings_options[api_key]’. That is why we are accessing the option’s value as an array item on line 3.

Although your options are stored automatically, you can register a sanitation function as we did in the register_setting function in step 1 called wpturbo_validate_options.

This is what this function will look like:

function wpturbo_validate_options( $input ) {
	$input['api_key'] = sanitize_text_field( $input['some_text_field'] );
    return $input;
}

This is what the final code for your settings page will look like:

<?php
function wpturbo_render_custom_settings_page() {
    ?>
    <h2>My Custom Plugin Settings Page</h2>
    <form action="options.php" method="post">
        <?php 
        settings_fields( 'wpturbo_api_settings_options' );
        do_settings_sections( 'api_key_settings' ); ?>
        <input name="submit" class="button button-primary" type="submit" value="Save Settings" />
    </form>
    <?php
}

function wpturbo_render_settings_section(){
	echo "<p>A quick description of this section displayed after the heading and before the fields.</p>"
}

function wpturbo_render_api_key_settings_field() {
    $options = get_option( 'wpturbo_api_settings_options' );
	$api_key = $options['api_key'];
    echo "<input id='wpturbo-api-key-settings-field' name='wpturbo_api_settings_options[api_key]' type='text' value='" . esc_attr( $api_key ) . "' />";
}

function wpturbo_validate_options( $input ) {
	$input['api_key'] = sanitize_text_field( $input['some_text_field'] );
    return $input;
}

function wpturbo_register_settings() {
    register_setting( 'wpturbo_api_settings_options', 'wpturbo_api_settings_options', 'wpturbo_validate_options' );
	
    add_settings_section( 'api_key_settings', 'API Settings', 'wpturbo_render_settings_section', 'wpturbo-custom-settings-page' );

    add_settings_field( 'wpturbo_api_key', 'Your API Key', 'wpturbo_render_api_key_settings_field', 'wpturbo-custom-settings-page', 'api_key_settings' );
}
add_action( 'admin_init', 'wpturbo_register_settings' );

Conclusion

Although creating a settings page in WordPress is really easy, if you aren’t familiar with how WordPress works, it can be a nightmare! Why not use our free, easy Settings Page Code Generator to generate this code for you? It offers a ton of options and will give you a quick template to get started.