---
url: /documentation/input-types/color.md
description: >-
  Configure color inputs with predefined colors or a picker, regex filtering,
  dropdown or inline display, and wpce_get_color().
---

# Color Input

Provide a choice of colors to select.

```js
{
  input: {
    type: 'color', // [!code focus:2]
    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:

```js
{
  input: {
    excludeColors: ['text-.+'], // [!code focus]
  }
}
```

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`](../../hooks/filters/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:

```php
$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 

Since WPCE , 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:**

```php
$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](/documentation/concepts/elements/definition#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. |