ColorPicker

Components/Form

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

Overview

Copy

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.

Copy

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.

Copy

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.

Copy

Hide bottom actions

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

Copy

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.

Copy

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.

Copy

History bar

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

Copy

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.

Copy

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.

Copy

Developer examples

Triggering the color picker

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

Copy

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.

Copy

Common use case examples

Custom color selection

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

Copy

Adding color to color swatch

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

Copy

Code

Copy

Props

NameTypeDefaultDescription
addTooltipContentReactNode—Defines content to show in add button tooltip. Doesn't appear if onAdd isn't passed.
allowEmptybooleanfalseAllows to submit when color isn't selected. Returns a color object with alpha equal to 0.
childrenReactNode | 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.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
emptyPlaceholderstring—Defines a placeholder text to show in an input when allowEmpty is true.
eyeDropperLabelstring'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.
removePaddingbooleanfalseSpecifies whether component padding should be removed.
showActionButtonsbooleantrueSpecifies whether action buttons (confirm/cancel) should be displayed.
showConverterbooleantrueSpecifies whether HEX/RGB/HSB converter tabs be displayed.
showEyeDropperbooleanfalseSpecifies whether eye dropper tool should be displayed.
showHistorybooleanfalseSpecifies whether current and previously used colors should be displayed.
showInputbooleantrueSpecifies 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)
  • 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)
  • 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)
  • 1.236.0 (2025-12-04) — fix: add removePadding type to index.d.ts (#15624)
  • 1.234.0 (2025-12-03) — feat: add removePadding prop to allow removing root component padding (#15613)
  • 1.233.0 (2025-12-02) — maintenance release, no component-specific changes
  • 1.228.0 (2025-11-18) — feat: eyeDropper and new layout (#15498)
  • 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)
  • 1.204.1 (2025-07-09) — fix: fix background color with surface-overlay token (#15065)
  • 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)
  • 1.169.0 (2025-03-10) — maintenance release, no component-specific changes
  • 1.166.0 (2025-03-04) — breaking: tokenization (#14568)
  • 1.145.0 (2024-12-09) — fix: add missing children to ColorPickerProps (#14365)
  • 1.121.0 (2024-08-13) — fix: fix focus propagation in modal (#14036)
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 30 October 2026

Did this help?