Browse: Home / Plugin Handbook / Settings / Using Settings API

Using Settings API

Topics

Adding Settings Adding Settings

You must define a new setting using register_setting(), it will create an entry in the {$wpdb->prefix}_options table.

You can add new sections on existing pages using add_settings_section().

You can add new fields to existing sections using add_settings_field().

Alert:
register_setting() as well as the mentioned add_settings_*() functions should all be added to the admin_init action hook.

Add a Setting Add a Setting

1
2
3
4
5
register_setting(
    string $option_group,
    string $option_name,
    callable $sanitize_callback = ''
);

Please refer to the Function Reference about register_setting() for full explanation about the used parameters.

Top ↑

Add a Section Add a Section

1
2
3
4
5
6
add_settings_section(
    string $id,
    string $title,
    callable $callback,
    string $page
);

Sections are the groups of settings you see on WordPress settings pages with a shared heading. In your plugin you can add new sections to existing settings pages rather than creating a whole new page. This makes your plugin simpler to maintain and creates fewer new pages for users to learn.

Please refer to the Function Reference about add_settings_section() for full explanation about the used parameters.

Top ↑

Add a Field Add a Field

1
2
3
4
5
6
7
8
add_settings_field(
    string $id,
    string $title,
    callable $callback,
    string $page,
    string $section = 'default',
    array $args = []
);

Please refer to the Function Reference about add_settings_field() for full explanation about the used parameters.

Top ↑

Example Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
<?php
function wporg_settings_init()
{
    // register a new setting for "reading" page
    register_setting('reading', 'wporg_setting_name');
 
    // register a new section in the "reading" page
    add_settings_section(
        'wporg_settings_section',
        'WPOrg Settings Section',
        'wporg_settings_section_cb',
        'reading'
    );
 
    // register a new field in the "wporg_settings_section" section, inside the "reading" page
    add_settings_field(
        'wporg_settings_field',
        'WPOrg Setting',
        'wporg_settings_field_cb',
        'reading',
        'wporg_settings_section'
    );
}
 
/**
 * register wporg_settings_init to the admin_init action hook
 */
add_action('admin_init', 'wporg_settings_init');
 
/**
 * callback functions
 */
 
// section content cb
function wporg_settings_section_cb()
{
    echo '<p>WPOrg Section Introduction.</p>';
}
 
// field content cb
function wporg_settings_field_cb()
{
    // get the value of the setting we've registered with register_setting()
    $setting = get_option('wporg_setting_name');
    // output the field
    ?>
    <input type="text" name="wporg_setting_name" value="<?php echo isset( $setting ) ? esc_attr( $setting ) : ''; ?>">
    <?php
}

Expand full source codeCollapse full source code

Top ↑

Getting Settings Getting Settings

1
2
3
4
get_option(
    string $option,
    mixed $default = false
);

Getting settings is accomplished with the get_option() function.
The function accepts two parameters: the name of the option and an optional default value for that option.

Top ↑

Example Example

1
2
// get the value of the setting we've registered with register_setting()
$setting = get_option('wporg_setting_name');