Adding custom settings fields to WordPress using add_settings_field

The add_settings_field function in WordPress is utilized to add a new field to a settings page. This function is part of the Settings API, which provides a standardized way of creating and managing settings pages and fields in the WordPress admin area.

By using add_settings_field, developers can define input fields that appear on a settings page, allowing users to enter and save configuration options. This function connects a specific field with a settings section, ensuring that the field is displayed within the correct context on the settings page.

The function facilitates the creation of custom settings interfaces by linking the new field with a callback function responsible for rendering the field’s HTML. Additionally, it helps in organizing settings fields by associating them with specific sections defined on the settings page.

add_settings_field serves as a key component in building custom settings pages, enabling the addition of various input fields to collect user-defined settings in a structured manner.

Parameters

The add_settings_field function accepts the following parameters:

  • $id (string), required. Slug-name to identify the field. Used in the ‘id’ attribute of tags.
  • $title (string), required. Formatted title of the field. Shown as the label for the field during output.
  • $callback (callable), required. Function that fills the field with the desired form inputs. The function should echo its output.
  • $page (string), required. The slug-name of the settings page on which to show the section (general, reading, writing, …).
  • $section (string), optional. Default value: ‘default’. The slug-name of the section of the settings page in which to show the box. Default ‘default’.
  • $args (array), optional. Default value: array(). Extra arguments that get passed to the callback function.
    • label_for (string). When supplied, the setting title will be wrapped in a <label> element, its for attribute populated with this value.
    • class (string). CSS Class to be added to the <tr> element when the field is output.

Return Value

The add_settings_field function does not return a value.

Examples

How to Add a Text Field to the General Settings Page

function myplugin_register_settings() {
 register_setting('general', 'myplugin_text_field');
 add_settings_field(
 'myplugin_text_field', 
 'My Plugin Text Field', 
 'myplugin_text_field_callback', 
 'general'
 );
}
add_action('admin_init', 'myplugin_register_settings');

function myplugin_text_field_callback() {
 $value = get_option('myplugin_text_field', '');
 echo '<input type="text" id="myplugin_text_field" name="myplugin_text_field" value="' . esc_attr($value) . '" />';
}

This snippet registers a new text field in the General Settings page of the WordPress admin dashboard. The myplugin_register_settings function registers the setting and adds the settings field. The myplugin_text_field_callback function outputs the HTML input element for the text field.

How to Add a Checkbox Field to the Reading Settings Page

function myplugin_register_checkbox() {
 register_setting('reading', 'myplugin_checkbox_field');
 add_settings_field(
 'myplugin_checkbox_field', 
 'My Plugin Checkbox', 
 'myplugin_checkbox_field_callback', 
 'reading'
 );
}
add_action('admin_init', 'myplugin_register_checkbox');

function myplugin_checkbox_field_callback() {
 $checked = get_option('myplugin_checkbox_field', false);
 echo '<input type="checkbox" id="myplugin_checkbox_field" name="myplugin_checkbox_field" value="1" ' . checked(1, $checked, false) . ' />';
}

This snippet registers a new checkbox field in the Reading Settings page of the WordPress admin dashboard. The myplugin_register_checkbox function registers the setting and adds the settings field. The myplugin_checkbox_field_callback function outputs the HTML checkbox input element.

Conclusion

The add_settings_field function in WordPress serves the purpose of adding individual settings fields to a settings section within the WordPress admin interface. This function is integral for developers who need to create custom settings pages or extend existing ones by introducing new fields for user input. By utilizing add_settings_field, developers can define the field’s title, description, and display callback, enabling a wide range of customization options. This function is particularly useful when paired with other settings API functions such as register_setting and add_settings_section, facilitating a comprehensive approach to managing and displaying custom settings in the WordPress admin dashboard.

Related WordPress Functions

in WordPress Functions