Components/Form/Swatches/Swatches
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/swatches
Swatches allows to display a list of predefined color options to choose from.
<FillPreview/> instead.<ColorInput/> instead.Specify a list of colors to show as swatches. Accepts HEX, RGB, HSL and string values.
Define the number of columns in a single row with the `columns` prop.
Define the gap between color swatches using the `gap` prop. It supports pixel units.
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.
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
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`.
Use swatches in composer panels to let users create color palettes for their product.
| 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. |
Import the driver matching your test environment:
| 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. |
Last updated: 22 October 2026