WordPress.org

Ready to get started?Download WordPress

Codex

Class Reference/WP Customize Manager/add setting

Contents

Description

Adds a new theme setting that can be customized using the Theme Customization API. This is a method of the WP_Customize_Manager() class and can only be accessed through the $wp_customize object within the customize_register action hook.

Usage

$wp_customize->add_setting($id, $args);

Parameters

$id
(string) (required) A unique slug-like ID for the theme setting.
Default: None
$args
(array) (required) An associative array containing arguments for the setting.
Default: None

Arguments

default
A default value for the setting if none is defined
type
Optional. Specifies the TYPE of setting this is. Options are 'option' or 'theme_mod' (defaults to 'theme_mod')
capability
Optional. You can define a capability a user must have to modify this setting
theme_supports
Optional. This can be used to hide a setting if the theme lacks support for a specific feature (using add_theme_support).
transport
Optional. This can be either 'refresh' (default) or 'postMessage'. Only set this to 'postMessage' if you are writing custom Javascript to control the Theme Customizer's live preview.
sanitize_callback
Optional. A function name to call for sanitizing the input value for this setting. The function should be of the form of a standard filter function, where it accepts the input data and returns the sanitized data.
sanitize_js_callback
Optional. A function name to call for sanitizing the value for this setting for the purposes of outputting to javascript code. The function should be of the form of a standard filter function, where it accepts the input data and returns the sanitized data. This is only necessary if the data to be sent to the customizer window has a special form.

One way to think of the difference between sanitize_callback and sanitize_js_callback is as input and output. The sanitize_callback will be invoked when data comes from the customizer to the database. The sanitize_js_callback will be invoked when data comes from the database back to the customizer.

Example

Remember that this example assumes you are already working within the customize_register action hook.

$wp_customize->add_setting( 'header_color' , array(
    'default' => '#000',
    'sanitize_callback' => 'sanitize_hex_color',
) );

Related

See also index of Class Reference and index of Function Reference.