WP_Customize_Manager::add_setting( WP_Customize_Setting|string $id, array $args = array() ): WP_Customize_Setting

Adds a customize setting.


See also


Customize Setting object, or ID.
Array of properties for the new Setting object.
See WP_Customize_Setting::__construct() for information on accepted arguments.



WP_Customize_Setting The instance of the setting that was added.


public function add_setting( $id, $args = array() ) {
	if ( $id instanceof WP_Customize_Setting ) {
		$setting = $id;
	} else {
		$class = 'WP_Customize_Setting';

		/** This filter is documented in wp-includes/class-wp-customize-manager.php */
		$args = apply_filters( 'customize_dynamic_setting_args', $args, $id );

		/** This filter is documented in wp-includes/class-wp-customize-manager.php */
		$class = apply_filters( 'customize_dynamic_setting_class', $class, $id, $args );

		$setting = new $class( $this, $id, $args );

	$this->settings[ $setting->id ] = $setting;
	return $setting;


apply_filters( ‘customize_dynamic_setting_args’, false|array $setting_args, string $setting_id )

Filters a dynamic setting’s constructor args.

apply_filters( ‘customize_dynamic_setting_class’, string $setting_class, string $setting_id, array $setting_args )

Allow non-statically created settings to be constructed with custom WP_Customize_Setting subclass.


4.5.0Return added WP_Customize_Setting instance.

User Contributed Notes

  1. Skip to note 3 content

    The sanitize_callback parameter needs to refer to a function that accepts at least two parameters or a variable argument length. The two parameters send to the callback are 1.) the value of the setting and 2.) the instance of WP_Customize_Setting. Using a callback that only accepts one parameter may result in a customize validation failiure upon saving or a PHP warning (see error log).

  2. Skip to note 4 content
    $wp_customize->add_setting( 'wpdocs_setting_id', array(
      'type' => 'theme_mod', // or 'option'
      'capability' => 'edit_theme_options',
      'theme_supports' => '', // Rarely needed.
      'default' => '',
      'transport' => 'refresh', // or postMessage
      'sanitize_callback' => '',
      'sanitize_js_callback' => '', // Basically to_json.
    ) );

You must log in before being able to contribute a note or feedback.