Adding Customizer Settings

Customizer Settings are added in a similar manner as Metaboxes and Options Pages, but there are some differences.

Group Setting Values

key	type	description
title	string	The title for customizer panel (required)
id	string	The id of customizer settings. This is the key under which the data will be saved. (required)
sections	array	The sections, which each have a group of fields.
option	string	Defines where data is saved. By default, this is saved in the options table as a theme mod. Accepts 'option' or 'theme_mod'. Defaults to 'theme_mod'.
panel	boolean	Whether to group the sections under the main panel or add them to the customizer directly. If panel is not set, or set to false, the sections will be added to the existing customizer screen.

Section Values

These values represent the keys for each section that may be added.

key	type	description
title	string	The title for customizer section (required)
id	string	The id of customizer section (required). Existing ids such as 'themes', 'title_tagline', 'colors', 'header_image', 'background_image' or 'static_front_page' are also accepted to add additional fields to existing customizer sections.
fields	array	The fields under this section
active_callback	string	Reference to a function name which is used to check if this panel should be rendered, such as 'is_page'.

Adding Fields

Customizer Fields have a different array structure as fields for Metaboxes or Options Pages and do not support all type of fields.

Common Field Properties

These properties are common for each field.

key	type	description
title	string	The title for the field(required)
id	string	The id of the field (required).
description	string	An optional description for this field.
type	array	The type of field. Supports built in values such as 'text', 'hidden', 'number', 'range', 'url', 'tel', 'email', 'search', 'time', 'date', 'datetime', 'week' or 'checkbox', 'textarea', 'radio', 'select', 'dropdown-pages'. Also support custom types from WP Custom fields such as 'colorpicker', 'cropped-image', 'image', 'media', 'upload', 'textarea', 'dimension', 'typography', 'custom' or ``''heading':
'``.
selector	string or array	The css selector to style with this field. See the section on custom styling.
transport	string	Determines if updating this field refreshes the whole view, or that values are transferred using custom JS. Accepts 'refresh or 'postMessage (for custom refreshing).
partial	array	Properties for a partial object. A partial allows you to render a component of the customizer front-end and edit this accordingly. See the codex for more information on accepted properties.
sanitize	string	Accepts a function name which is used to sanitize input.
sanitize_js	string	Accepts a function name which is used to sanitize js input.
custom	string	The complete, namespaced reference to a custom class that is rendering a field. Allows to add custom customizer fields.

Additional Field Properties

These properties only apply to some fields.

key	type	description
choices	array	Array of options for a select field, such as ['option' => 'Label', 'option_2' => 'Label 2'];
input_attrs	array	Array of input attributes, such as '['min' => 0, 'max' => 10]'
mime_type	string	The allowed mime_type for any 'image', 'media' or 'upload' type.
height	int	Height of a field
width	int	Width of a field

We invite you to play around with the different field types to see what their effect is.

Custom Styling & Refreshing with postMessage

WP Custom Fields has some built-in functions to refresh the customizer partially. It allows to dynamically add content or styling without a full refresh of the customizer preview window. For now, this is supported for textual content and color picker fields.

The following example of a field array changes the background colour of the element with the class 'header'

array(
    'default'       => '',
    'selector'      => array( 'selector' => '.header', 'property' => 'background-color' ),
    'id'            => 'new_field_value26',
    'title'         => __('Example Color', 'wp-custom-fields'),
    'description'   => __('Add an example color', 'wp-custom-fields'),
    'transport'     => 'postMessage',
    'type'          => 'colorpicker',
),

The following example of a field array inserts the content in the element with the class 'copyright', while using the customizer.

    array(
        'default'       => '',
        'selector'      => array( 'selector' => '.copyright', 'html' => true ),
        'id'            => 'new_field_value27',
        'title'         => __('Example Content', 'wp-custom-fields'),
        'transport'     => 'postMessage',
        'type'          => 'textarea',
),

The selector property accepts the following properties:

key	type	description
selector

If the selector key is a string

Examples