> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: ColorPicker Component

## Article: ColorPicker Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/form/color-picker-component.md

## Article Content:

# ColorPicker

_Components/Form_

Interactive docs page: <https://wix-pages.com/design-system-documentation/#/component/colorpicker>

## Overview

```jsx
() => {
  const [value, setValue] = React.useState('orchid');
  const [colors, setColors] = React.useState([
    'cornsilk',
    'cornflowerblue',
    'darkseagreen',
    'lavender',
  ]);

  return (
    <Box direction="vertical" align="center">
      <ColorPicker
        value={value}
        showEyeDropper
        showConverter={false}
        onChange={(color) => setValue(color.hex())}
        onCancel={setValue}
        onAdd={(color) => setColors([...colors, color])}
      >
        {({ changeColor }) => (
          <>
            <Swatches
              colors={colors}
              onClick={(color) => {
                changeColor(color);
              }}
            />
          </>
        )}
      </ColorPicker>
    </Box>
  );
};
```

Color picker allows users to select a color value by dragging the cursor inside of a color spectrum. It's a popover that should be called out via `<ColorInput/>`, `<Button/>` or another component.

It uses this color manipulation library: <https://github.com/Qix-/color>

### Do

- Use it to freely select any solid color.
- Use it to show the full spectrum of available colors to select.

### Don't

- Don't use it to select one color from a predefined set of colors. Use `<Swatches/>` instead.

### Feature examples

#### Structure

The component consists of a color spectrum canvas, an input area, and a `children` area.

Set the initial color using the `value` prop. The `children` area accepts any content, typically used for color swatches.

```jsx
<ColorPicker value="#3899EC">
  <StorybookComponents.Placeholder>
    Any required content
  </StorybookComponents.Placeholder>
</ColorPicker>;
```

#### Removing padding

By default, the component includes padding designed for popover use.

Remove the padding to embed the color picker inside other layouts, such as modals, panels, or cards, by setting the `removePadding` prop to true.

```jsx
<StorybookComponents.Stack>
  <StorybookComponents.Stack>
    <ColorPicker value="#3899EC" />
  </StorybookComponents.Stack>
  <StorybookComponents.Stack height="100%">
    <ColorPicker value="#3899EC" removePadding />
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

#### Color converter

Enables to view and edit color codes in HEX/RGB/HSB formats. Converter is visible by default and can be hidden on demand by setting the `showConverter` to false.

```jsx
<StorybookComponents.Stack>
  <StorybookComponents.Stack>
    <ColorPicker value="#3899EC" />
  </StorybookComponents.Stack>
  <StorybookComponents.Stack height="100%">
    <ColorPicker value="#3899EC" showConverter={false} />
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

#### Hide bottom actions

Bottom actions are shown by default. To hide them for specific use cases, set the `showActionButtons` prop to false.

```jsx
<StorybookComponents.Stack>
  <StorybookComponents.Stack>
    <ColorPicker value="#3899EC" />
  </StorybookComponents.Stack>
  <StorybookComponents.Stack height="100%">
    <ColorPicker value="#3899EC" showActionButtons={false} />
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

#### Color dropper

Enable the eye dropper tool using the `showEyeDropper` prop. When used together with the color converter, the eye dropper appears next to it. If `showConverter` is false, the eye dropper displays inline with the input area.

Use `eyeDropperLabel` prop to customize the eye dropper button label if needed.

```jsx
<StorybookComponents.Stack>
  <StorybookComponents.Stack>
    <ColorPicker value="#3899EC" showEyeDropper />
  </StorybookComponents.Stack>
  <StorybookComponents.Stack height="100%">
    <ColorPicker
      value="#3899EC"
      showEyeDropper
      showConverter={false}
      eyeDropperLabel="Pick a color"
    />
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

#### Hide color value input

To restrict color selection to visual picking only, hide the color value input by setting `showInput` to false. The `showConverter` prop must also be set to false.

```jsx
<ColorPicker value="#3899EC" showConverter={false} showInput={false} />;
```

#### History bar

Compare the currently active color with a newly picked one before confirming a change. Enable this by using the `showHistory` prop.

```jsx
<ColorPicker value="#3899EC" showHistory={true} />;
```

#### Accept empty value

Allow to submit an empty value with `allowEmpty` prop. Use for non-mandatory color selection.

Use the `emptyPlaceholder` prop to define the placeholder message shown in HEX value input.

```jsx
<ColorPicker
  value=""
  allowEmpty={true}
  emptyPlaceholder={'No color picked'}
/>;
```

#### Add color presets

Enable users to build a custom palette by saving frequently used colors. An add button lets users add the current color to the swatches list.

Pass the `<Swatches/>` component to children and use the `onAdd` property to handle adding new swatches.

```jsx
() => {
  const [value, setValue] = React.useState('#3899EC');
  const [presets, setPresets] = React.useState([
    'midnightblue',
    'darkmagenta',
    'lightcoral',
  ]);
  return (
    <ColorPicker
      value={value}
      onAdd={(color) => setPresets([...presets, color])}
      addTooltipContent="Add color"
    >
      <Swatches colors={presets} onClick={setValue} />
    </ColorPicker>
  );
};
```

### Developer examples

#### Triggering the color picker

Call out the picker popover on any component click, for example `<Multiselect/>`.

```jsx
() => {
  const [colors, setColors] = React.useState([
    { id: '1', color: 'red' },
    { id: '2', color: 'blue' },
    { id: '3', color: 'green' },
  ]);
  const updateColors = ({ id, color }) =>
    setColors(
      colors.map((item) => (item.id === id ? { ...item, color } : item)),
    );
  const TagThumb = ({ color }) => (
    <Box
      backgroundColor={color}
      marginTop="24%"
      marginLeft="24%"
      borderRadius="50%"
      height="50%"
      width="50%"
    />
  );
  const TagPopover = (props) => {
    const [color, setColor] = React.useState(props.color);
    const [shown, setShown] = React.useState(false);
    return (
      <Popover
        showArrow
        shown={shown}
        appendTo="window"
        onClick={() => setShown(!shown)}
        onClickOutside={() => setShown(false)}
      >
        <Popover.Element>
          <Text>{color}</Text>
        </Popover.Element>
        <Popover.Content>
          <ColorPicker
            value={color}
            onCancel={() => setShown(!shown)}
            onConfirm={(value) => {
              setShown(false);
              updateColors({ id: props.id, color: value.hex() });
              setColor(value.hex());
            }}
            onChange={() => {}}
          />
        </Popover.Content>
      </Popover>
    );
  };
  const tags = colors.map(({ color, id }) => ({
    id,
    label: <TagPopover color={color} id={id} />,
    thumb: <TagThumb color={color} />,
  }));
  return (
    <MultiSelect
      tags={tags}
      mode="select"
      placeholder="Select tags from a list"
    />
  );
};
```

#### Adding color swatches

Allow users to select a color from a list of presets by adding `<Swatches/>` to the `children` area above the submit actions.

```jsx
() => {
  const [value, setValue] = React.useState('#3899EC');
  const [colors, setColors] = React.useState([
    'midnightblue',
    'darkmagenta',
    'lightcoral',
  ]);

  return (
    <ColorPicker
      value={value}
      onChange={setValue}
      onCancel={setValue}
      onAdd={(color) => setColors([...colors, color])}
    >
      {({ changeColor }) => (
        <Swatches
          colors={colors}
          onClick={(color) => {
            changeColor(color);
          }}
        />
      )}
    </ColorPicker>
  );
};
```

### Common use case examples

#### Custom color selection

Use `colorPickerChildren` props inside `<ColorInput/>` to let users select and input custom color values.

```jsx
() => {
  const [value, setValue] = React.useState('#3899EC');
  const [presets, setPresets] = React.useState([
    'midnightblue',
    'darkmagenta',
    'lightcoral',
  ]);
  return (
    <Box>
      <StorybookComponents.Stack flexDirection="column">
        <FormField label="Text color">
          <ColorInput
            value={value}
            onChange={setValue}
            colorPickerChildren={({ changeColor }) => (
              <Swatches colors={presets} onClick={changeColor} />
            )}
          />
        </FormField>
      </StorybookComponents.Stack>
    </Box>
  );
};
```

#### Adding color to color swatch

Use `<ColorPicker/>` with `<Swatches/>` to let users add new colors to a palette.

```jsx
() => {
  const [value, setValue] = React.useState(null);
  const [colors, setColors] = React.useState(['tomato', 'thistle', 'tan']);

  return (
    <FormField label="Background color">
      <Box>
        <Swatches
          showAddButton
          addButtonIconSize="small"
          addButtonMessage="Add color"
          onAdd={(color) => setColors([...colors, color])}
          colors={colors}
          onClick={setValue}
          selected={value}
          renderColorPicker={({ cancel, confirm, setColor, currentColor }) => (
            <ColorPicker
              value={currentColor}
              showEyeDropper
              showInput={true}
              showConverter={true}
              onCancel={cancel}
              onConfirm={confirm}
              onChange={setColor}
            />
          )}
        />
      </Box>
    </FormField>
  );
};
```

## Code

```jsx
import { ColorPicker } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `addTooltipContent` | `ReactNode` | — | Defines content to show in add button tooltip. Doesn't appear if `onAdd` isn't passed. |
| `allowEmpty` | `boolean` | `false` | Allows to submit when color isn't selected. Returns a color object with alpha equal to 0. |
| `children` | `ReactNode \| ColorPickerChildrenRenderer` | — | Defines child items to be rendered above action buttons. Accepts any kind of content, or a function that receives `{ changeColor }` to control the picker's color and returns the content. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `emptyPlaceholder` | `string` | — | Defines a placeholder text to show in an input when `allowEmpty` is true. |
| `eyeDropperLabel` | `string` | `'Sample color'` | Defines the label for the eye dropper button. |
| `onAdd` | `(color: string) => void` | — | Defines an event handler for color add button click, called with the color's HEX string. If not passed, the plus icon won't be visible. |
| `onCancel` | `(color: string \| Color) => void` | — | Defines an event handler for cancel button click. |
| `onChange` | `(color: string \| Color) => void` | — | Defines an event handler for color change. |
| `onConfirm` | `(color: string \| Color) => void` | — | Defines an event handler for confirm button click. |
| `removePadding` | `boolean` | `false` | Specifies whether component padding should be removed. |
| `showActionButtons` | `boolean` | `true` | Specifies whether action buttons (confirm/cancel) should be displayed. |
| `showConverter` | `boolean` | `true` | Specifies whether `HEX`/`RGB`/`HSB` converter tabs be displayed. |
| `showEyeDropper` | `boolean` | `false` | Specifies whether eye dropper tool should be displayed. |
| `showHistory` | `boolean` | `false` | Specifies whether current and previously used colors should be displayed. |
| `showInput` | `boolean` | `true` | Specifies whether color input in HEX mode should be displayed. This is relevant only if `showConverter` is `false` |
| `value` *(required)* | `string \| Color` | — | Defines current color. It accepts a `string` or an `object`, in the formats supported by the `color` library, for example `#3899EC` or `rgb(56, 153, 236)`. |

## Testkit

No testkit for this component — it doesn't expose a unidriver testkit.

## Changelog

- **1.344.0** (2026-10-28) — maintenance release, no component-specific changes
- **1.340.0** (2026-10-21) — maintenance release, no component-specific changes
- **1.339.0** (2026-10-19) — maintenance release, no component-specific changes
- **1.338.0** (2026-10-15) — maintenance release, no component-specific changes
- **1.336.0** (2026-10-13) — maintenance release, no component-specific changes
- **1.335.0** (2026-10-12) — maintenance release, no component-specific changes
- **1.330.0** (2026-09-28) — maintenance release, no component-specific changes
- **1.329.0** (2026-09-24) — maintenance release, no component-specific changes
- **1.328.0** (2026-09-22) — maintenance release, no component-specific changes
- **1.326.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.323.0** (2026-09-10) — maintenance release, no component-specific changes
- **1.320.0** (2026-09-03) — maintenance release, no component-specific changes
- **1.310.0** (2026-08-10) — maintenance release, no component-specific changes
- **1.305.1** (2026-07-30) — maintenance release, no component-specific changes
- **1.295.0** (2026-07-03) — maintenance release, no component-specific changes
- **1.292.0** (2026-06-22) — maintenance release, no component-specific changes
- **1.278.0** (2026-05-08) — maintenance release, no component-specific changes
- **1.270.0** (2026-04-20) — fix: made touch sensitive things not interact with page scroll ([#16157](invalid-url))
- **1.266.0** (2026-04-07) — maintenance release, no component-specific changes
- **1.260.0** (2026-03-17) — maintenance release, no component-specific changes
- **1.247.2** (2026-01-21) — maintenance release, no component-specific changes
- **1.243.0** (2025-12-23) — feat: add focus method to set focus on the first interactive element ([#15711](invalid-url))
- **1.242.0** (2025-12-19) — maintenance release, no component-specific changes
- **1.241.0** (2025-12-17) — maintenance release, no component-specific changes
- **1.237.0** (2025-12-08) — fix: set padding to zero for noPadding class (#15633) ([#15635](invalid-url))
- **1.236.0** (2025-12-04) — fix: add removePadding type to index.d.ts ([#15624](invalid-url))
- **1.234.0** (2025-12-03) — feat: add removePadding prop to allow removing root component padding ([#15613](invalid-url))
- **1.233.0** (2025-12-02) — maintenance release, no component-specific changes
- **1.228.0** (2025-11-18) — feat: eyeDropper and new layout ([#15498](invalid-url))
- **1.221.0** (2025-10-15) — maintenance release, no component-specific changes
- **1.212.0** (2025-08-11) — maintenance release, no component-specific changes
- **1.207.0** (2025-07-24) — fix: focus ring missing on add new color button ([#15102](invalid-url))
- **1.204.1** (2025-07-09) — fix: fix background color with surface-overlay token ([#15065](invalid-url))
- **1.204.0** (2025-07-03) — maintenance release, no component-specific changes
- **1.200.0** (2025-06-17) — maintenance release, no component-specific changes
- **1.199.0** (2025-06-13) — feat: added showActionButtons prop ([#14980](invalid-url))
- **1.169.0** (2025-03-10) — maintenance release, no component-specific changes
- **1.166.0** (2025-03-04) — breaking: tokenization ([#14568](invalid-url))
- **1.145.0** (2024-12-09) — fix: add missing children to `ColorPickerProps` ([#14365](invalid-url))
- **1.121.0** (2024-08-13) — fix: fix focus propagation in modal ([#14036](invalid-url))
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes