How to Use Settings API in WordPress: Simple Guide

Use the WordPress Settings API by registering settings with register_setting(), adding sections with add_settings_section(), and fields with add_settings_field(). Then display the settings form using settings_fields(), do_settings_sections(), and submit_button() inside your admin page callback.

Syntax

The Settings API uses these main functions:

• register_setting( $option_group, $option_name, $args ): Registers a setting to be saved.
• add_settings_section( $id, $title, $callback, $page ): Adds a section to group fields.
• add_settings_field( $id, $title, $callback, $page, $section, $args ): Adds a field to a section.
• settings_fields( $option_group ): Prints hidden fields for security in the form.
• do_settings_sections( $page ): Prints all sections and fields for the page.
• submit_button(): Prints the save button.

These functions work together to create a settings page that saves options securely.

php

register_setting( 'my_option_group', 'my_option_name' );
add_settings_section( 'my_section_id', 'Section Title', 'section_callback', 'my_page_slug' );
add_settings_field( 'my_field_id', 'Field Title', 'field_callback', 'my_page_slug', 'my_section_id' );

Example

This example creates a simple settings page with one text field saved in the database.

php

<?php
add_action('admin_menu', function() {
    add_options_page('My Settings', 'My Settings', 'manage_options', 'my-settings', 'my_settings_page');
});

add_action('admin_init', function() {
    register_setting('my_option_group', 'my_option_name');

    add_settings_section('my_section', 'My Section', function() {
        echo '<p>Enter your settings below:</p>';
    }, 'my-settings');

    add_settings_field('my_field', 'My Text Field', function() {
        $value = get_option('my_option_name', '');
        echo '<input type="text" name="my_option_name" value="' . esc_attr($value) . '" />';
    }, 'my-settings', 'my_section');
});

function my_settings_page() {
    ?>
    <div class="wrap">
        <h1>My Settings</h1>
        <form method="post" action="options.php">
            <?php
            settings_fields('my_option_group');
            do_settings_sections('my-settings');
            submit_button();
            ?>
        </form>
    </div>
    <?php
}
?>

Output

<p>A WordPress admin page titled "My Settings" with a text input field and a save button. When saved, the input value is stored in the database option <code>my_option_name</code>.</p>

Common Pitfalls

• Not calling settings_fields() inside the form causes security nonce errors and prevents saving.
• Forgetting to hook register_setting() and field/section functions to admin_init means settings won't register.
• Using mismatched $page slugs between add_settings_section(), add_settings_field(), and the form causes fields not to display.
• Not sanitizing input in register_setting() $args can lead to unsafe data saved.

php

<?php
// Wrong: Missing settings_fields() in form
function wrong_settings_page() {
    ?>
    <form method="post" action="options.php">
        <?php do_settings_sections('my-settings'); ?>
        <?php submit_button(); ?>
    </form>
    <?php
}

// Right: Include settings_fields() for nonce and option group
function right_settings_page() {
    ?>
    <form method="post" action="options.php">
        <?php settings_fields('my_option_group'); ?>
        <?php do_settings_sections('my-settings'); ?>
        <?php submit_button(); ?>
    </form>
    <?php
}
?>

Quick Reference

Function	Purpose	Required Parameters
register_setting	Register a setting for saving	$option_group, $option_name
add_settings_section	Add a section to group fields	$id, $title, $callback, $page
add_settings_field	Add a field to a section	$id, $title, $callback, $page, $section
settings_fields	Print security fields in form	$option_group
do_settings_sections	Print all sections and fields	$page
submit_button	Print save button	none

Key Takeaways

Always register your settings, sections, and fields inside the admin_init hook.

Use settings_fields() inside your form to handle security nonces and option groups.

Match the $page slug in add_settings_section(), add_settings_field(), and your form.

Sanitize user input by providing a callback in register_setting() to keep data safe.

The Settings API simplifies creating admin settings pages that save options securely.