WordPress.org

Languages: English • 日本語 (Add your language)

Description

Register a settings field to a settings page and section.

This is part of the Settings API, which lets you automatically generate wp-admin settings pages by registering your settings and using a few callbacks to control the output.

This function assumes you already know the settings $page and the page $section that the field should be shown on.

You MUST register any options used by this function with register_setting() or they won't be saved and updated automatically.

The callback function needs to output the appropriate html input and fill it with the old value, the saving will be done behind the scenes.

The html input field's name attribute must match $option_name in register_setting(), and value can be filled using get_option().

This function can also be used to add extra settings fields to the default WP settings pages like media or general. You can add them to an existing section, or use add_settings_section() to create a new section to add the fields to.

See Settings API for details.

Usage

<?php add_settings_field( $id, $title, $callback, $page, $section, $args ); ?>

Parameters

$id

(string) (required) String for use in the 'id' attribute of tags.

Default: None

$title

(string) (required) Title of the field.

Default: None

$callback

(callback) (required) Function that fills the field with the desired inputs as part of the larger form. Passed a single argument, the $args array. Name and id of the input should match the $id given to this function. The function should echo its output.

Default: None

$page

(string) (required) The menu page on which to display this field. Should match $menu_slug from add_theme_page() or from do_settings_sections().

Default: None

$section

(string) (optional) The section of the settings page in which to show the box (default or a section you added with add_settings_section(), look at the page in the source to see what the existing ones are.)

Default: default

$args

(array) (optional) Additional arguments that are passed to the $callback function. The 'label_for' key/value pair can be used to format the field title like so: <label for="value">$title</label>.

Default: array()

Return Values

(void) 

This function does not return a value.

Examples

With Label

Adds a setting with id "myprefix_setting-id" to the General Settings page. "myprefix" should be a unique string for your plugin or theme. Sets a label so that the setting title can be clicked on to focus on the field.

add_settings_field(
	'myprefix_setting-id',
	'This is the setting title',
	'myprefix_setting_callback_function',
	'general',
	'myprefix_settings-section-name',
	array( 'label_for' => 'myprefix_setting-id' )
);

Change Log

Since: 2.7.0

Source File

add_settings_field() is located in wp-admin/includes/template.php.

Related

Settings API: register_setting(), unregister_setting(), add_settings_field(), add_settings_section(), add_settings_error(), get_settings_errors(), settings_errors()