add_settings_field()
Add a new field to a section of a settings page
Part of the Settings API. Use this to define a settings field that will show as part of a settings section inside a settings page. The fields are shown using do_settings_fields() in do_settings_sections().
The $callback argument should be the name of a function that echoes out the HTML input tags for this setting field. Use get_option() to retrieve existing values to show.
No Hooks.
Return
null. Nothing (null).
Usage
add_settings_field( $id, $title, $callback, $page, $section, $args );
- $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)
- The slug-name of the section of the settings page in which to show the box.
Default: 'default' - $args(array)
Extra arguments that get passed to the callback function.
Default: array()
-
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.
-
Examples
#1 Add a new option field to the main WordPress settings page (general).
myprefix must be unique, for example with some prefix of your plugin or theme. Also, let's pass the last parameter where we specify id and option name for the corresponding tag attributes:
<?php
add_action( 'admin_menu', 'add_option_field_to_general_admin_page' );
function add_option_field_to_general_admin_page() {
$option_name = 'my_option';
// register the option
register_setting( 'general', $option_name );
// add a field
add_settings_field(
'myprefix_setting-id',
'Option Name',
'myprefix_setting_callback_function',
'general',
'default',
[
'id' => 'myprefix_setting-id',
'option_name' => 'my_option'
]
);
}
function myprefix_setting_callback_function( $val ) {
$id = $val['id'];
$option_name = $val['option_name'];
?>
<input
type="text"
name="<?= $option_name ?>"
id="<?= $id ?>"
value="<?= esc_attr( get_option( $option_name ) ) ?>"
/>
<?php
}
As a result, on the "general" page, at the very end, we get a new fully working option:
#2 OOP Usage template
class ClassName {
public function __construct() {
add_action( 'admin_init', [ $this, 'your_function' ] );
}
function your_function() {
add_settings_field(
'myprefix_setting-id',
'This is the setting title',
[ $this, 'myprefix_setting_callback_function' ],
'general',
'default',
[ 'label_for' => 'myprefix_setting-id' ]
);
}
function myprefix_setting_callback_function( $args ) {
echo 'Content here';
}
}
$ClassName = new ClassName(); #3 Checkbox settings field
A checkbox settings field can be checked on the front end by simply looking for isset. No need to add additional checks like 1, 0, true, false… . if a checkbox is not set then it returns false.
add_action( 'admin_menu', 'add_option_field_to_general_admin_page' );
function add_option_field_to_general_admin_page() {
// settings checkbox
add_settings_field(
'wpdevref_removestyles_field',
esc_attr__( 'Remove Plugin Styles', 'wpdevref' ),
'wpdevref_removestyles_field_cb',
'general',
'default',
[
'type' => 'checkbox',
'option_group' => 'wpdevref_options',
'name' => 'wpdevref_removestyles_field',
'label_for' => 'wpdevref_removestyles_field',
'value' => (int) ( get_option( 'wpdevref_options' )['wpdevref_removestyles_field'] ?? 0 ),
'description' => __( 'Check to remove preset plugin overrides.', 'wpdevref' ),
'checked' => get_option( 'wpdevref_options' )['wpdevref_removestyles_field'] ?? 0,
// Used 0 in this case but will still return Boolean not[see notes below]
'tip' => esc_attr__( 'Use if plugin fields drastically changed when installing this plugin.', 'wpdevref' ),
]
);
}
/**
* switch for 'remove styles' field
* @since 2.0.1
* @input type checkbox
*/
function wpdevref_removestyles_field_cb( $args ) {
$options = get_option( $args['option_group'] );
$value = $options[ $args['name'] ] ?? null;
// Could use ob_start.
$html = '
<label title="{TIP}">
<input id="{ID}" name="{NAME}" type="checkbox" {CHECKED}/>
<span class="wndspan">{DESCRIPTION}</span>
<b class="wntip">?</b>
</label>
';
$html = strtr( $html, [
'{TIP}' => esc_attr( $args['tip'] ),
'{ID}' => esc_attr( $args['name'] ),
'{NAME}' => esc_attr( $args['option_group'] . "[{$args['name']}]" ),
'{CHECKED}' => $value ? ' checked="checked" ' : '',
'{DESCRIPTION}' => esc_html( $args['description'] ),
] );
echo $html;
}
and checking to render action on the front side would use:
// Options getter could be a function with arguments.
$options = get_option( 'wpdevref_options' );
$value = $options['wpdevref_removestyles_field'] ?? '';
if( ! $value ){
// Do some
}
Optionally you can add a ‘false’ into any conditional( empty, null, ”, 0 ) .
Notes
- Global. Array. $wp_settings_fields Storage array of settings fields and info about their pages/sections.
Changelog
| Since 2.7.0 | Introduced. |
| Since 4.2.0 | The $class argument was added. |