ColorInput

Components/Form

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

Overview

Copy

Color input allows the user to select a color, either by using a visual color picker or by entering the HEX color code manually into the text field.

Do

  • Use it to specify a custom color for any item.

Don't

  • Don't use it to select a color from a predefined list of options. Use <Swatches/> instead.

Feature examples

Size

Adjust the component's size using the size prop. It supports 3 sizes:

  • Use large to emphasize the input field.
  • Use medium for all common cases (default).
  • Use small when the layout is dense and narrow.
Copy

Status

Indicate the component's status using the status prop. It has three states:

  • Use the error state to indicate an invalid value (e.g., a HEX value that doesn't exist).
  • Use the warning state to highlight a value that can cause an unwanted result (e.g., text color is the same as the background color).
  • Use the loading state to show the value is currently being saved or validated.
Copy

Status message

Add text that explains the status or what action the user should take with the statusMessage prop.

Showing the status message inline, directly below the input is preferred in all default cases.

  • To add an accessible inline message, wrap the component in a <FormField/> and add the statusMessage.
  • To add a status message in a tooltip that requires users to hover on the icon, use the statusMessage prop. Control tooltip placement with tooltipPlacement prop.

View more inline status message examples in <FormField/>.

Copy

Disabled

Prevent the user from using the color input field with the disabled prop. Use it to indicate that the field is unavailable for editing (e.g., if the element already has a pre-defined color that can't be changed).

Copy

Popover

Adjust the placement and behavior of the color picker popover by using any of the properties in popoverProps. Check the <Popover/> component API for a full list.

Copy

Add color presets

Allow users to add new color presets inside the color picker by clicking an "Add color" button. Use a combination of the colorPickerChildren and the onAddColor properties to add this ability.

Copy

Common use case examples

Custom text color

Use color input in a variety of composers to define custom colors for text, background fills, icons, etc.

Copy

Code

Copy

Props

NameTypeDefaultDescription
addTooltipContentReactNode—Defines content to show in add button tooltip. Doesn't appear if onAdd isn't passed.
ariaControlsstring—Associate a control with the regions that it controls.
ariaDescribedbystring—Associate a region with its descriptions. Similar to aria-controls but instead associating descriptions to the region and description identifiers are separated with a space.
ariaLabelstring—Define a string that labels the current element in case where a text label isn't visible on the screen.
ariaRoledescriptionstring—Sets the aria-roledescription attribute of the <input> element, giving assistive technologies a readable description of its role.
autocompletestring—Sets the value of the native autocomplete attribute, for example off or email.
autoFocusboolean—Focus the element on mount (standard React input autoFocus)
autoSelectboolean—Automatically selects the entire input text.
backgroundColorstring—Sets the background color of the input. Accepts any CSS color value.
border"none" | "standard" | "round" | "bottomLine"—Control the border style of input.
childrenReactNode—
clearButtonboolean—Displays clear button (X) on a non-empty input.
clearButtonAriaLabelstring—Aria label for the clear button.
clearButtonTooltipContentReactNode—When provided, hovering displays a tooltip with this content.
clearButtonTooltipPropsTooltipCommonProps—Clear button tooltip props.
colorPickerChildrenReactNode | ColorPickerChildrenRenderer—Defines child items to render inside of a component. Accepts any kind of content, or a function that receives { changeColor } to control the <ColorInput/> value and returns the content.
customInputReactNode | Function—Render a custom input instead of the default html input tag.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
defaultValuestring | number—Defines the initial value of an input.
disabledboolean—Specifies whether input should be disabled or not.
disableEditingboolean—Restricts input editing.
enterKeyHint"search" | "enter" | "done" | "go" | "next" | "previous" | "send"—Sets the label of the virtual keyboard's enter key on touch devices.
focusOnClearClickboolean—Specifies whether to focus the field when clear button is clicked.
hideStatusSuffixboolean—Specifies whether status suffix should be hidden.
idstring—Assigns a unique identifier for the root element.
inputmodestring—Sets the value of the native inputmode attribute, which tells mobile browsers which on-screen keyboard to show, for example numeric or email.
inputRefnull | (instance: HTMLInputElement | null) => void | RefObject<HTMLInputElement>—Ref to the underlying <input> DOM element. Accepts callback and object refs. Use for input masking libraries such as use-mask-input. Memoize callback refs to avoid reattaching on every render.
maxnumber—Sets a maximum value of an input. Similar to html5 max attribute.
maxLengthnumber—Sets the maximum number of characters that can be inserted to a field.
menuArrowboolean—Specifies whether input should have a dropdown menu arrow on the right side.
minnumber—Sets a minimum value of an input. Similar to HTML5 min attribute.
namestring—Reference element data when a form is submitted.
noLeftBorderRadiusboolean—Specifies whether input shouldn't have rounded corners on its left.
noRightBorderRadiusboolean—Specifies whether input shouldn't have rounded corners on its right.
onAddColor(color: string) => void—Defines a callback handler with color HEX string. Handler is called whenever the Add Color button is pressed.
onBlurFocusEventHandler—Defines a standard input onBlur callback.
onCancel(color: string | object) => void—Returns last confirmed value from value prop.
onChange(color: string | object) => void—Returns changed value of input or color picker.
onClear(event: KeyboardEvent<HTMLButtonElement> | MouseEvent<HTMLButtonElement, MouseEvent>) => void—Displays clear button (X) on a non-empty input and calls a callback function.
onCompositionChange(isComposing: boolean) => void—Defines a callback function called on compositionstart/compositionend events.
onConfirm(color: string | object) => void—Returns confirmed value.
onCopyClipboardEventHandler<HTMLInputElement>—Defines a callback handler that is called when user copies text to a clipboard (using a mouse or keyboard shortcut)
onEnterPressedKeyboardEventHandler<HTMLInputElement>—Defines a callback handler that is called when the user presses -enter-.
onEscapePressedKeyboardEventHandler<HTMLInputElement>—Defines a callback handler that is called when the user presses -escape-.
onFocusFocusEventHandler—Defines a standard input onFocus callback.
onInputClickedMouseEventHandler—Defines a standard input onClick callback.
onKeyDownKeyboardEventHandler<HTMLInputElement>—Defines a standard input onKeyDown callback.
onKeyUpKeyboardEventHandler<HTMLInputElement>—Defines a standard input onKeyUp callback.
onPasteClipboardEventHandler<HTMLInputElement>—Defines a callback handler that is called when user pastes text from a clipboard (using a mouse or keyboard shortcut)
patternstring—Sets a pattern that typed value must match to be valid (regex)
placeholderstring''Sets a placeholder message to display.
popoverAppendTo"window" | "scrollParent" | "viewport" | "parent"—Sets the element the color-picker popover is rendered into.
popoverPlacement"right" | "left" | "top" | "bottom" | "auto" | "auto-start" | "auto-end" | "top-start" | "top-end" | "right-start" | "right-end" | "bottom-end" | "bottom-start" | "left-end" | "left-start"—Controls where the color-picker popover opens relative to the input.
popoverPropsOmit<PopoverNextProps, "children" | "dataHook" | "onClickOutside" | "placement" | "appendTo" | "fixed" | "showArrow" | "shown" | "open" | "onOpenChange">—Accepts popover props that are passed to the color picker popover.
prefixReactNode—Pass a component you want to show as the prefix of the input, e.g., text, icon.
readOnlyboolean—Specifies whether input is read only.
refnull | string | (instance: ColorInputComponent | null) => void | RefObject<ColorInputComponent>—Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref).
requiredboolean—Specifies whether input is mandatory.
rolestring—Specifies the role of the input element for accessibility.
rtlboolean—Specifies text direction. If true, the text is displayed from right to left.
showDrawerOnMobilebooleantrueSpecifies whether the color picker opens in a bottom <Drawer/> when WixDesignSystemProvider has mobile enabled.
size"small" | "medium" | "large"'medium'Controls the size of the input. Default value: medium
status"error" | "warning" | "loading"—Specify the status of a field.
statusMessageReactNode—Defines the message to display on status icon hover. If not given or empty, no tooltip is displayed.
statusMessageTooltipPropsTooltipCommonProps—Status message tooltip props.
stepnumber—Specifies the interval between number values.
suffixReactNode—Pass a component you want to show as the suffix of the input, e.g., text, icon.
tabIndexnumber—Indicates that element can be focused and where it participates in sequential keyboard navigation.
textOverflow"ellipsis" | "clip"—Handles text overflow behavior. It can either clip (default) or display ellipsis.
tooltipPlacement"right" | "left" | "top" | "bottom" | "auto" | "auto-start" | "auto-end" | "top-start" | "top-end" | "right-start" | "right-end" | "bottom-end" | "bottom-start" | "left-end" | "left-start"—Controls placement of a status tooltip.
typestring—Specifies the type of <input/> element to display. Default is text.
valuestring''Specifies the current value of the element.
withSelectionboolean—

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
cancelCancels color selection
confirmConfirms color selection
clickColorViewerClicks on color viewer box
enterTextEnters text to color input
getValueGets the input value
getPlaceholderGets the placeholder of the input
getSizeGets the input size
isDisabledChecks whether the input is disabled
colorPickerVisibleChecks whether the color picker is visible
clickClicks on input
hasStatusChecks whether the given status is displayed
getStatusMessageGets the status message
existsChecks whether the component found with the given data hook.
elementGets the component root element.
baseReturns UniDriver for the base element.

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.331.0 (2026-10-01) — maintenance release, no component-specific changes
  • 1.330.3 (2026-09-29) — maintenance release, no component-specific changes
  • 1.330.0 (2026-09-28) — 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.312.0 (2026-08-14) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — 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.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.279.0 (2026-05-13) — 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.247.2 (2026-01-21) — maintenance release, no component-specific changes
  • 1.233.0 (2025-12-02) — maintenance release, no component-specific changes
  • 1.221.0 (2025-10-15) — fix: not closing when focus leaves the picker panel (#15396)
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.109.2 (2024-06-17) — maintenance release, no component-specific changes
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.98.0 (2024-03-15) — maintenance release, no component-specific changes
  • 1.93.0 (2024-02-08) — 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?