add_settings_field()WP 2.7.0

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.

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 used when outputting the field.

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

0

#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:

What did the admin page get in the Basic page

0

#2 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 ) .

0

#3 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();

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.

Code of add_settings_field() WP 6.0.1

function add_settings_field( $id, $title, $callback, $page, $section = 'default', $args = array() ) {
	global $wp_settings_fields;

	if ( 'misc' === $page ) {
		_deprecated_argument(
			__FUNCTION__,
			'3.0.0',
			sprintf(
				/* translators: %s: misc */
				__( 'The "%s" options group has been removed. Use another settings group.' ),
				'misc'
			)
		);
		$page = 'general';
	}

	if ( 'privacy' === $page ) {
		_deprecated_argument(
			__FUNCTION__,
			'3.5.0',
			sprintf(
				/* translators: %s: privacy */
				__( 'The "%s" options group has been removed. Use another settings group.' ),
				'privacy'
			)
		);
		$page = 'reading';
	}

	$wp_settings_fields[ $page ][ $section ][ $id ] = array(
		'id'       => $id,
		'title'    => $title,
		'callback' => $callback,
		'args'     => $args,
	);
}