> 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: Swatches Component

## Article: Swatches Component

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

## Article Content:

# Swatches

_Components/Form/Swatches/Swatches_

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

## Overview

```jsx
() => {
  const [value, setValue] = React.useState(null);
  const [colors, setColors] = React.useState([
    '#3370fb',
    '#7852d2',
    '#17b0e2',
    '#c53e99',
    '#fdb10c',
    '#3d9fa1',
  ]);

  return (
    <FormField label="Color" required>
      <Box>
        <Swatches
          showClear
          showAddButton
          showClearMessage="Clear Color"
          addButtonMessage="New Color"
          onAdd={(color) => setColors([...colors, color])}
          selected={value}
          onClick={setValue}
          colors={colors}
        />
      </Box>
    </FormField>
  );
};
```

Swatches allows to display a list of predefined color options to choose from.

### Do

- Use it to select a single color from a predefined color palette.
- Use it to display solid color options.
- Use it to create a list of color options when used with ColorPicker.

### Don't

- Don't use it to display gradient or image fill options. Use `<FillPreview/>` instead.
- Don't use it to select a custom color, use `<ColorInput/>` instead.

### Feature examples

#### Colors

Specify a list of colors to show as swatches. Accepts HEX, RGB, HSL and string values.

```jsx
<StorybookComponents.Stack>
  <Swatches
    colors={[
      '#3370fb',
      '#17b0e2',
      '#c53e99',
      'rgb(200,250,0)',
      'hsl(10,100%,50%)',
      'teal',
    ]}
  />
</StorybookComponents.Stack>;
```

#### Columns

Define the number of columns in a single row with the \`columns\` prop.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <StorybookComponents.Stack>
    6 columns:
    <Swatches
      columns={6}
      colors={[
        '#3370fb',
        '#7852d2',
        '#17b0e2',
        '#c53e99',
        '#fdb10c',
        '#3d9fa1',
      ]}
    />
  </StorybookComponents.Stack>
  <StorybookComponents.Stack>
    3 columns:
    <Swatches
      columns={3}
      colors={[
        '#3370fb',
        '#7852d2',
        '#17b0e2',
        '#c53e99',
        '#fdb10c',
        '#3d9fa1',
      ]}
    />
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

#### Gap

Define the gap between color swatches using the \`gap\` prop. It supports pixel units.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <StorybookComponents.Stack>
    12px gap:
    <Swatches
      gap={12}
      colors={[
        '#3370fb',
        '#7852d2',
        '#17b0e2',
        '#c53e99',
        '#fdb10c',
        '#3d9fa1',
      ]}
    />
  </StorybookComponents.Stack>
  <StorybookComponents.Stack>
    24px gap:
    <Swatches
      gap={24}
      colors={[
        '#3370fb',
        '#7852d2',
        '#17b0e2',
        '#c53e99',
        '#fdb10c',
        '#3d9fa1',
      ]}
    />
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

#### Clear color

Allows user to select a 'Clear color' option. This option is added as a first item on the list using the \`showClear\` prop. Provide an explanatory message with the \`showClearMessage\` prop.

```jsx
<StorybookComponents.Stack>
  <Swatches
    showClear
    showClearMessage="Clear color"
    colors={[
      '#3370fb',
      '#7852d2',
      '#17b0e2',
      '#c53e99',
      '#fdb10c',
      '#3d9fa1',
      '#2bc759',
      '#ff0165',
    ]}
  />
</StorybookComponents.Stack>;
```

#### Add button

Add a new color swatch using the:\
 - \`showAddButton\` - specify whether to add button is visible\
 - \`addButtonIconSize\` - control the plus icon size within the button\
 - \`showAddButtonMessage\` - show action description in a tooltip\
 - \`onAdd\` - calls assigned function\
 - \`popoverProps\` - control the color picker popover by passing props

```jsx
<StorybookComponents.Stack>
  <Swatches
    showAddButton
    addButtonIconSize="small"
    addButtonMessage="Message explaining add action"
    onAdd={() => {}}
    colors={['#3370fb', '#7852d2', '#17b0e2', '#c53e99', '#fdb10c']}
  />
</StorybookComponents.Stack>;
```

#### ColorPicker customization

Customize the ColorPicker by using \`renderColorPicker\` prop. This render prop provides full control over the color picker UI. Use it to configure the default ColorPicker with custom props like \`showInput\` and \`showConverter\`.

```jsx
<StorybookComponents.Stack>
  <Swatches
    showAddButton
    addButtonIconSize="small"
    addButtonMessage="Add color with input"
    renderColorPicker={({ cancel, confirm, setColor, currentColor }) => (
      <ColorPicker
        value={currentColor}
        showInput={true}
        showConverter={true}
        onCancel={cancel}
        onConfirm={confirm}
        onChange={setColor}
      />
    )}
    onAdd={() => {}}
    colors={['#3370fb', '#7852d2', '#17b0e2', '#c53e99', '#fdb10c']}
  />
</StorybookComponents.Stack>;
```

### Common use case examples

#### Inside Color Picker

Use swatches in composer panels to let users create color palettes for their product.

```jsx
() => {
  const [value, setValue] = React.useState(null);
  const [colors, setColors] = React.useState([
    '#3370fb',
    '#7852d2',
    '#17b0e2',
    '#c53e99',
    '#fdb10c',
    '#3d9fa1',
    '#2bc759',
    '#ff0165',
  ]);

  return (
    <FormField label="Fill">
      <Box>
        <Swatches
          showAddButton
          addButtonIconSize="small"
          addButtonMessage="Add color"
          onAdd={(color) => setColors([...colors, color])}
          showClear
          showClearMessage="Clear color"
          colors={colors}
          onClick={setValue}
          selected={value}
        />
      </Box>
    </FormField>
  );
};
```

## Code

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

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `addButtonIconSize` | `"small" \| "medium"` | — | Controls the size of a plus icon inside of the add button. |
| `addButtonMessage` | `string` | — | Specifies a message to display on 'Add' button hover. If not provided, the tooltip won't be displayed. |
| `colors` | `(string \| object)[]` | — | Defines an array of colors to be shown as swatches. |
| `columns` | `number` | `6` | Specifies a number of columns in a single row. Default value is 6. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `gap` | `number` | `12` | Specifies a gap between swatches in pixels. Default value is 12px. |
| `onAdd` | `(hexColor: string) => void` | — | Defines a callback function for 'Add' button click. Returns color HEX string representation once user selects a color to be added. |
| `onCancel` | `() => void` | — | Defines a callback function for color picker popover 'Cancel' action (user closes it without picking color). |
| `onChange` | `(hexColor: string) => void` | — | Defines a callback function for color change. Returns color HEX string representation. |
| `onClick` | `string \| object` | — | Defines a callback function for  user click on a swatch. Returns color HEX string representation. |
| `popoverProps` | `PopoverCommonProps` | — | Props that get passed to New color popover. |
| `renderColorPicker` | `(params: { cancel: () => void; confirm: () => void; setColor: (color: Color) => void; currentColor: Color; }) => ReactNode` | — | Custom render function for the color picker. Provides full control over the color picker UI and behavior. |
| `selected` | `string` | — | Specifies which color from the list is in a selected state. |
| `showAddButton` | `boolean` | — | Specifies whether New color' button is displayed or not. Add button opens up a color picker. |
| `showClear` | `boolean` | — | Specifies whether to display a 'No color' option as a first item on a list or not. |
| `showClearMessage` | `ReactNode` | — | Defines a message to display on 'No color' option hover. `showClear` must be set to true. |
| `size` | `"small" \| "medium"` | — | Size of swatches. |

## Testkit

Import the driver matching your test environment:

```jsx
// UniDriver
import { SwatchesUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { SwatchesTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { SwatchesTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { SwatchesTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| Method | Description |
| --- | --- |
| `getSwatchCount` | Get swatch count |
| `getSwatch` | Get swatch at given index |
| `clickEmptySwatch` | Click empty swatch |
| `isSwatchSelectedAt` | Test if swatch is selected at given index |
| `isEmptySwatchSelected` | Test if empty swatch is selected |
| `addButtonExists` | — |
| `exists` | Checks whether the component found with the given data hook. |
| `element` | Gets the component root element. |
| `click` | Clicks on the component root element. |
| `base` | Returns UniDriver for the base element. |

## Changelog

- **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.331.0** (2026-10-01) — maintenance release, no component-specific changes
- **1.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.310.0** (2026-08-10) — maintenance release, no component-specific changes
- **1.292.0** (2026-06-22) — maintenance release, no component-specific changes
- **1.291.0** (2026-06-19) — maintenance release, no component-specific changes
- **1.279.0** (2026-05-13) — maintenance release, no component-specific changes
- **1.272.0** (2026-04-27) — maintenance release, no component-specific changes
- **1.271.0** (2026-04-22) — maintenance release, no component-specific changes
- **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.241.0** (2025-12-17) — maintenance release, no component-specific changes
- **1.228.0** (2025-11-18) — maintenance release, no component-specific changes
- **1.221.1** (2025-10-16) — maintenance release, no component-specific changes
- **1.221.0** (2025-10-15) — feat: add renderColorPicker prop ([#15412](invalid-url))
- **1.220.0** (2025-09-29) — maintenance release, no component-specific changes
- **1.104.0** (2024-05-06) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes