CSS Style Output & Customizer Refresh

WP Custom Fields allows transferring the values of the field to custom styling for Customizer, Meta and Option Fields.

Defining Style Output

A number of fields have the possibility to output their values as CSS. Outputting is done by specifying the given selector using the 'selector' property for a field:

[
    'default'       => '',
    'selector'      => '.header',
    'id'            => 'colorpicker_id_field',
    'title'         => __('Example Color', 'wp-custom-fields'),
    'description'   => __('Add an example color', 'wp-custom-fields'),
    'type'          => 'colorpicker',
],

The above is the array of settings for a single field. The above will change the color (text-color) for the element indicated with .header (the class).

Supported Fields

The following fields are supported, and they output the specified properties by defaylt:

field	default CSS properties
'background'	background-image, background-color, background-repeat, background-attachment and background-size
'boxshadow'	box-shadow
'colorpicker'	color
'dimension'	padding
'dimensions'	padding
'media'	background-image
'cropped-image' (customizer only)	background-image
'image' (customizer only)	background-image
'upload' (customizer only)	background-image
'typography'	font-family, font-size, line-height, font-weight, color

Custom Selector Properties

It is also possible to specify the CSS property you want to target and set a custom query. By default, 'selector' is a string matching the CSS selector you want to target, but it can also be an array. If the selector is not a string, it accepts the following properties:

key	type	description
selector	string	The selector, such as '.site-header'.
property	string	A custom property to style, such as 'background-color'. Works best with 'colorpicker', 'dimension' and 'dimensions' fields.
max-width	string	Sets the media query using max-width. Overwrites min-width, you can't have both selectors yet.
min-width	string	Sets the media query using min-width.
HTML	boolean	Whether to output the values of a given field as HTML to the given selector. Only applies to the customizer.
attr	string	The name of a custom attribute of to which you want to add the customizer field value. This allows changing attributes such as 'href' using partial refresh with 'postMessage'. Only applies to the customizer.

If the selector key is a string, such as '.site-header', it will use the default output of the field to match it with the styles for the given selector. For example, if you have a colour-picker field with a selector value of '.site-header', it will result in the following styling rule: '.site-header { color: $fieldValue; }'.

The following sets the background-color for .site-header, with only for screens with a max-width of 1024px;

[
    'default'       => '',
    'selector'      => [
        'selector'  => '.site-header',
        'property'  => 'background-color',
        'max-width' => '1024px',
    ]
    'id'            => 'colorpicker_id_other_field',
    'title'         => __('Example Color', 'wp-custom-fields'),
    'description'   => __('Add an example color', 'wp-custom-fields'),
    'type'          => 'colorpicker',
],

Customizer Refresh

It also has some built-in functions to refresh fields for 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 colour picker fields. This is done by setting the 'transfer' property of a field to 'postMessage'.

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

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',
),