Color Input

Provide a choice of colors to select.

{
  input: {
    type: 'color', 
    colorPicker: true
  }
}

Input Options

Option	Values	Default	Description
colors	string[]	[]	Only show these colors (color IDs). You might use regular expressions to match multiple.
excludeColors	string[]	[]	Exclude these colors (color IDs) from the list. You might use regular expressions to match multiple.
colorPicker	boolean	false	Whether to allow free color choice via the color picker.
allowEmpty	boolean	false	Whether to allow actively picking no color.
display	'dropdown' | 'inline'	'dropdown'	Whether display selectable colors as a dropdown or a row of colored buttons.

Matching Multiple Colors With Regular Expressions

For options mentioned above to be able to use regular expressions (i.e. the colors and the excludeColors options), you can use regular expressions to select mutliple colors at once. E.g. if you want all except text-* colors you could do something like this:

{
  input: {
    excludeColors: ['text-.+'], 
  }
}

The ^ and $ modifiers are automatically added at the start and end of each id. This is necessary as otherwise all ids would be matched partially (eg. "text" would automatically match all IDs starting with "text").

Define Colors

Learn more about managing colors in the wpce_colors hook.

Template Usage

To use a color property in your template use the wpce_get_color() function and pass the element's color property as shown below:

$props = $element->properties;
$color = wpce_get_color($props->myColor);
$style = $color
  ? "background-color: {$color->css->rgba}"
  : '';

Whereas $props->myColor stands for the element's color property.

The structure of the returned object looks like this:

stdClass Object
(
    [hex] => #3190cf
    [alpha] => 1
    [rgba] => stdClass Object
        (
            [r] => 49
            [g] => 144
            [b] => 207
            [a] => 1
        )

    [css] => stdClass Object
        (
            [rgba] => rgba(49,144,207,1)
        )

)

INFO

• If no color has been selected, null is returned.
• The hex property is always a 7-character string (including the leading #), but without alpha information.

Get a Certain Aspect of a Color v3.28

Since WPCE v3.28, you can pass a WPCE\ColorAspect enum case as the second argument to the wpce_get_color() function to get a certain aspect of a color directly. The following aspects are supported:

Case	Description
ID	The ID of the selected color (or null if a custom color was picked).
Hex	The hex value of the selected color, with a leading hash symbol. Note that (other than in the object returned by default) the hex string may also contain alpha information.
RGBA	An RGBA object of the color, with r, g and b ranging from 0 to 255 and a ranging from 0 to 1.
CSS	A CSS string representation of the color in rgb(r g b) resp. rgb(r g b / a) format.
All	The full color object as returned by default.

Example:

$props = $element->properties;
$color_id = wpce_get_color($props->myColor, WPCE\ColorAspect::ID);
$style = $color_id
  ? "background-color: var(--color-{$color_id})"
  : '';

Conditions

The color input type supports the following conditions for dynamic visibility:

Condition	Payload	Description
isEmpty	boolean defaults to true	Checks whether a color has been selected or not.
hasPicked	string	Checks whether the selected color has the given payload ID.