🛠 Adicionar um campo personalizado às definições do WordPress: add_settings_field

Standard WordPress settings cover most day-to-day tasks. But sooner or later you need a field that does not exist in the admin: a company phone number in the General section, a service API key, a license number field, or footer text.

Theme and plugin developers handle this through the Settings API, a set of WordPress functions for registering their own sections and fields on standard settings pages. The key one is add_settings_field(): it adds a custom field to a specified section and page.

By the end of this tutorial you will have working code that outputs a text field in the admin, saves the value to the database, and displays it on the site. No third-party plugins, just the built-in API.

💡 Quick overview:

• Prepare your environment: create a child theme or install the Code Snippets plugin so your code does not get wiped when the parent theme updates.
• Register the setting: call register_setting() on the admin_init hook, otherwise WordPress will not save the field data.
• Add a section and a field: use add_settings_section() for a new block and add_settings_field() for the input field inside it.
• Output the value: use get_option() anywhere in a template to display the saved data on the site.

What add_settings_field is and where it is used

The add_settings_field() function appeared in WordPress 2.7.0 and has remained the primary tool for extending settings pages ever since. According to the WordPress documentation, it adds a new field to an existing section on one of the admin pages.

What this means in practice. You can output an extra field on any standard page: General (general), Writing (writing), Reading (reading), Discussion (discussion), or Media (media). And if you created your own settings page via add_options_page(), the field will go there as well.

Typical scenarios:

• A "Contact phone" field in the general settings section, so the manager does not need to touch code to update the number.
• An API key field for your plugin, where the user enters the key in the admin instead of editing wp-config.php.
• A group of fields for a custom section (phone, email, address), using add_settings_section() plus multiple add_settings_field() calls.

Note: add_settings_field() only outputs the field HTML. The actual saving is handled by register_setting(); without it WordPress will ignore the entered data.

Add_settings_field syntax and parameters

The function signature, four required parameters and two optional ones:

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

Let's go through each parameter.

$id, the unique field identifier. This value becomes the HTML id attribute of the <input> tag you output in the callback function. Use a prefix to avoid conflicts, for example myplugin_phone_number.

$title, the field label displayed in the admin to the left of the input itself. Write it clearly: "Contact phone", "Service API key".

$callback, the name of your function that outputs the field HTML (input, textarea, select). This is where you write echo. The function must be declared beforehand; pass it as a string: 'my_field_callback'.

$page, the settings page slug. Standard values: general, reading, writing, discussion, and media. If you created a custom page, use its slug. Determines where the field appears.

$section (optional), the slug of the section the field belongs to. Defaults to 'default', which is the topmost section on the page. If you created your own section via add_settings_section(), specify its ID here.

$args (optional), an array of extra settings. Supported keys are label_for (the value of the HTML for attribute on the <label>) and class (a CSS class for the field wrapper).

All parameters and their behavior are described in the official Settings API guide on WordPress.org.

Practical example: adding a text field to General Settings

Let's put it all together. The goal: output a "Contact phone" text field on the Settings → General page, save the entered value, and retrieve it with get_option().

The code goes into the child theme's functions.php or via the Code Snippets plugin. The second option is safer: the snippet will not get wiped on a theme update.

1
// Callback to output the section description
2
function my_custom_section_callback() {
3
    echo 'Contact information for the organization. Phone number is displayed in the site footer.';
4
}
5
 
6
// Callback to output the input field
7
function my_phone_field_callback() {
8
    $value = get_option( 'my_contact_phone', '' );
9
    echo '<input 
10
        name="my_contact_phone" 
11
        type="text" 
12
        id="my_contact_phone" 
13
        value="' . esc_attr( $value ) . '" 
14
        class="regular-text" 
15
        placeholder="+1 (555) 123-4567" 
16
    />';
17
}
18
 
19
// Register the section and field
20
function my_register_settings() {
21
    // Register the setting — without this, data will not be saved
22
    register_setting( 'general', 'my_contact_phone' );
23
 
24
    // Add a section to the General settings page
25
    add_settings_section(
26
        'my_contact_section',            // Section ID
27
        'Contact Information',            // Section title
28
        'my_custom_section_callback',    // Callback for description
29
        'general'                         // Page slug
30
    );
31
 
32
    // Add a field to the section
33
    add_settings_field(
34
        'my_contact_phone',              // Field ID
35
        'Contact Phone',                  // Field label
36
        'my_phone_field_callback',       // Callback to render the field
37
        'general',                        // Page slug
38
        'my_contact_section'             // Section ID
39
    );
40
}
41
add_action( 'admin_init', 'my_register_settings' );

What happens here line by line. register_setting() tells WordPress: save the value of the my_contact_phone field as an option in the wp_options table when "Save Changes" is clicked on the general page.

add_settings_section() creates a new block with the heading "Organization contacts" on the general settings page. The my_custom_section_callback() callback outputs the description text above the section fields.

add_settings_field() places our field inside that section and links it to the my_phone_field_callback() callback, which renders <input type="text">. The get_option() function inserts the saved value into the value attribute, and esc_attr() escapes the output.

All the code is hooked to admin_init, which fires when the admin loads and guarantees that the section and field are already registered by the time the settings page renders.

After adding the code, open wp-admin/options-general.php and you will see the result:

Enter a number, click Save Changes, and the value is written to the database. To display the phone number on the site, use get_option() anywhere in a template:

1
$phone = get_option( 'my_contact_phone', '' );
2
if ( $phone ) {
3
    echo '<a href="tel:' . esc_attr( $phone ) . '">' . esc_html( $phone ) . '</a>';
4
}

Where to put the code and how to test

Three placement options, from worst to best.

Parent theme (functions.php). Do not do this. When the theme updates, the file gets overwritten and your customization disappears.

Child theme (****functions.php** of the child theme).** A workable option for edits tied to a specific site. The code survives parent theme updates.

Code Snippets plugin. The best choice for testing and long-term maintenance. You can enable/disable the snippet with one click, without touching the filesystem. Plus you get isolation: if the snippet causes a fatal error, WordPress automatically deactivates it and the site will not go down.

Testing procedure. Create a full site backup (database + files), this is standard precaution for any admin edit. Add the code using your chosen method. Open the settings page and verify the field is displayed. Enter a value and save. Check persistence: refresh the page, the field should be populated with what you entered.

If the field does not appear, check that you did not mix up the section ID in the $section parameter of add_settings_field(). A common mistake: the section is created with one ID, but a different one is passed to the field.

Video tutorial on the topic

To reinforce the material, watch a video walkthrough of the Settings API by a WordPress developer. It shows the full cycle: registering a section, adding a field, saving, and outputting on the site.

⁉️🤔 Frequently asked questions

Can I add multiple fields to one section?

Yes. Call add_settings_field() as many times as you need fields. Pass the same section ID in the $section parameter. Each field gets a unique $id and its own callback. The order of add_settings_field() calls determines the field order on the page.

How do I add a select, textarea, or checkbox instead of a text field?

The field type is set inside the callback function via HTML. For a select, build a <select> with <option> tags; for a textarea, a <textarea> tag; for a checkbox, <input type="checkbox">. The value is saved the same way via register_setting() and retrieved via get_option(). The specifics are only in the HTML.

Do I need to escape output in the callback?

Yes, absolutely. Use esc_attr() for attribute values (value, name, id) and esc_html() for text between tags. This protects against XSS and ensures that special characters in the saved value do not break the layout.

Can I add a field to my own plugin's page?

Yes. Create a page via add_options_page() or add_menu_page(), then register sections and fields the same way. Use your page's slug in the $page parameter of add_settings_field(). The mechanics are no different from standard pages.

What if the value does not save after clicking "Save Changes"?

You almost certainly skipped register_setting(). Without this function, WordPress does not know the field needs to be saved and ignores it on submit. Check: the first parameter of register_setting() must match the page name (e.g., 'general'), and the second must match your field's name attribute.

Bottom line: when extending admin settings makes sense

The WordPress Settings API is a mature and stable mechanism: add_settings_field() has not changed since version 2.7 and remains relevant in 2026. Adding your own fields to the admin is justified in three cases:

• You are developing a theme or plugin and want to give the user an interface for entering data, without editing code.
• You need a site-level setting field (phone number, API key, catalog ID) and it should be accessible through the admin, not through wp-config.php.
• You are customizing a client site and want the manager to be able to change data themselves without contacting the developer.

If the field is only for you and changes once a year, it is simpler to hardcode the value. The Settings API shines where settings are used by someone other than the developer.

Start simple: add one text field following the example above. Once you master the basic flow, registration, callback, saving, output, move on to selects, field groups, and custom settings pages. And which field type do you work with most often? Let us know in the comments.