Swatches

Components/Form/Swatches/Swatches

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

Overview

Copy

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.

Copy

Columns

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

Copy

Gap

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

Copy

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.

Copy

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

Copy

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`.

Copy

Common use case examples

Inside Color Picker

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

Copy

Code

Copy

Props

NameTypeDefaultDescription
addButtonIconSize"small" | "medium"—Controls the size of a plus icon inside of the add button.
addButtonMessagestring—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.
columnsnumber6Specifies a number of columns in a single row. Default value is 6.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
gapnumber12Specifies 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.
onClickstring | object—Defines a callback function for user click on a swatch. Returns color HEX string representation.
popoverPropsPopoverCommonProps—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.
selectedstring—Specifies which color from the list is in a selected state.
showAddButtonboolean—Specifies whether New color' button is displayed or not. Add button opens up a color picker.
showClearboolean—Specifies whether to display a 'No color' option as a first item on a list or not.
showClearMessageReactNode—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:

Copy

Driver methods

MethodDescription
getSwatchCountGet swatch count
getSwatchGet swatch at given index
clickEmptySwatchClick empty swatch
isSwatchSelectedAtTest if swatch is selected at given index
isEmptySwatchSelectedTest if empty swatch is selected
addButtonExists—
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns 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)
  • 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

Last updated: 22 October 2026

Did this help?