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

## Article: ColorInput Component

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

## Article Content:

# ColorInput

_Components/Form_

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

## Overview

```jsx
() => {
  const [value, setValue] = React.useState('#3899EC');
  return (
    <Box align="center">
      <StorybookComponents.Stack flexDirection="column" width={'30%'}>
        <FormField label="Color">
          <ColorInput value={value} onChange={setValue} />
        </FormField>
      </StorybookComponents.Stack>
    </Box>
  );
};
```

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.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <ColorInput placeholder="Large" size="large" />
  <ColorInput placeholder="Medium" size="medium" />
  <ColorInput placeholder="Small" size="small" />
</StorybookComponents.Stack>;
```

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <ColorInput value="#FF0000" status="error" />
  <ColorInput value="#FF0000" status="warning" />
  <ColorInput value="#FF0000" status="loading" />
</StorybookComponents.Stack>;
```

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <StorybookComponents.Stack flexDirection="column" gap="12px">
    <Text secondary>For all default cases:</Text>
    <FormField status="error" statusMessage="This is an error message.">
      <ColorInput placeholder="See message below" />
    </FormField>
  </StorybookComponents.Stack>
  <StorybookComponents.Stack flexDirection="column" gap="12px">
    <Text secondary>For narrow layouts only:</Text>
    <ColorInput
      placeholder="Hover on status icon"
      status="error"
      statusMessage="This is an error message."
    />
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

#### 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).

```jsx
() => {
  const [presets, setPresets] = React.useState([
    'midnightblue',
    'darkmagenta',
    'lightcoral',
  ]);
  return (
    <ColorInput
      value="#FF4136"
      disabled
      addTooltipContent="Add Color"
      onAddColor={(color) => setPresets([...presets, color])}
      colorPickerChildren={({ changeColor }) => (
        <Swatches colors={presets} onClick={changeColor} />
      )}
    />
  );
};
```

#### Popover

Adjust the placement and behavior of the color picker popover by using any of the properties in `popoverProps`. Check the [`<Popover/>`](https://wix-pages.com/design-system-documentation/#/component/popover) component API for a full list.

```jsx
<StorybookComponents.Stack>
  <StorybookComponents.Stack flexDirection="column" gap="6px">
    <Text size="small">Popover placement: Left</Text>
    <ColorInput
      value="#FF4136"
      popoverPlacement="left"
      popoverAppendTo="viewport"
    />
  </StorybookComponents.Stack>
  <StorybookComponents.Stack flexDirection="column" gap="6px">
    <Text size="small">Animate: true</Text>
    <ColorInput
      value="#FF4136"
      popoverProps={{
        animate: true,
      }}
    />
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

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

```jsx
() => {
  const [presets, setPresets] = React.useState([
    'midnightblue',
    'darkmagenta',
    'lightcoral',
  ]);
  return (
    <ColorInput
      value="#FF4136"
      addTooltipContent="Add Color"
      onAddColor={(color) => setPresets([...presets, color])}
      colorPickerChildren={({ changeColor }) => (
        <Swatches colors={presets} onClick={changeColor} />
      )}
    />
  );
};
```

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

```jsx
() => {
  const [color, setColor] = React.useState('#000000');
  const [alignment, setAlignment] = React.useState(0);
  const [text, setText] = React.useState('Luna Boutique');

  return (
    <SidePanel>
      <SidePanel.Header title="Customise text"></SidePanel.Header>
      <SidePanel.Content>
        <Box direction="vertical" gap="30px">
          <Text size="small" secondary>
            Change the font, color and more to make your text stand out.
          </Text>
          <FormField label="Edit text">
            <Input value={text} onChange={(e) => setText(e.target.value)} />
          </FormField>
          <FormField label="Font">
            <Box gap="6px">
              <Text weight="bold">Playfair Display - 700</Text>
              <Button size="tiny" priority="secondary">
                Change Font
              </Button>
            </Box>
          </FormField>
          <FormField label="Alignment">
            <Box gap="6px">
              <ToggleButton
                labelValue="Left"
                selected={alignment === 0}
                onClick={() => setAlignment(0)}
              >
                <Icons.TextAlignLeft />
              </ToggleButton>
              <ToggleButton
                labelValue="Center"
                selected={alignment === 1}
                onClick={() => setAlignment(1)}
              >
                <Icons.TextAlignCenter />
              </ToggleButton>
              <ToggleButton
                labelValue="Right"
                selected={alignment === 2}
                onClick={() => setAlignment(2)}
              >
                <Icons.TextAlignRight />
              </ToggleButton>
            </Box>
          </FormField>
          <FormField label="Text color">
            <ColorInput
              value={color}
              onChange={setColor}
              popoverAppendTo="viewport"
            />
          </FormField>
        </Box>
      </SidePanel.Content>
      <SidePanel.Footer>
        <Box align="right" gap="12px">
          <Button size="small" priority="secondary">
            Discard Changes
          </Button>
          <Button size="small">Save</Button>
        </Box>
      </SidePanel.Footer>
    </SidePanel>
  );
};
```

## Code

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

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `addTooltipContent` | `ReactNode` | — | Defines content to show in add button tooltip. Doesn't appear if `onAdd` isn't passed. |
| `ariaControls` | `string` | — | Associate a control with the regions that it controls. |
| `ariaDescribedby` | `string` | — | 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. |
| `ariaLabel` | `string` | — | Define a string that labels the current element in case where a text label isn't visible on the screen. |
| `ariaRoledescription` | `string` | — | Sets the `aria-roledescription` attribute of the `<input>` element, giving assistive technologies a readable description of its role. |
| `autocomplete` | `string` | — | Sets the value of the native `autocomplete` attribute, for example `off` or `email`. |
| `autoFocus` | `boolean` | — | Focus the element on mount (standard React input autoFocus) |
| `autoSelect` | `boolean` | — | Automatically selects the entire input text. |
| `backgroundColor` | `string` | — | Sets the background color of the input. Accepts any CSS color value. |
| `border` | `"none" \| "standard" \| "round" \| "bottomLine"` | — | Control the border style of input. |
| `children` | `ReactNode` | — |  |
| `clearButton` | `boolean` | — | Displays clear button (X) on a non-empty input. |
| `clearButtonAriaLabel` | `string` | — | Aria label for the clear button. |
| `clearButtonTooltipContent` | `ReactNode` | — | When provided, hovering displays a tooltip with this content. |
| `clearButtonTooltipProps` | `TooltipCommonProps` | — | Clear button tooltip props. |
| `colorPickerChildren` | `ReactNode \| 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. |
| `customInput` | `ReactNode \| Function` | — | Render a custom input instead of the default html input tag. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `defaultValue` | `string \| number` | — | Defines the initial value of an input. |
| `disabled` | `boolean` | — | Specifies whether input should be disabled or not. |
| `disableEditing` | `boolean` | — | Restricts input editing. |
| `enterKeyHint` | `"search" \| "enter" \| "done" \| "go" \| "next" \| "previous" \| "send"` | — | Sets the label of the virtual keyboard's enter key on touch devices. |
| `focusOnClearClick` | `boolean` | — | Specifies whether to focus the field when clear button is clicked. |
| `hideStatusSuffix` | `boolean` | — | Specifies whether status suffix should be hidden. |
| `id` | `string` | — | Assigns a unique identifier for the root element. |
| `inputmode` | `string` | — | Sets the value of the native `inputmode` attribute, which tells mobile browsers which on-screen keyboard to show, for example `numeric` or `email`. |
| `inputRef` | `null \| (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. |
| `max` | `number` | — | Sets a maximum value of an input. Similar to html5 max attribute. |
| `maxLength` | `number` | — | Sets the maximum number of characters that can be inserted to a field. |
| `menuArrow` | `boolean` | — | Specifies whether input should have a dropdown menu arrow on the right side. |
| `min` | `number` | — | Sets a minimum value of an input. Similar to HTML5 min attribute. |
| `name` | `string` | — | Reference element data when a form is submitted. |
| `noLeftBorderRadius` | `boolean` | — | Specifies whether input shouldn't have rounded corners on its left. |
| `noRightBorderRadius` | `boolean` | — | 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. |
| `onBlur` | `FocusEventHandler` | — | 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. |
| `onCopy` | `ClipboardEventHandler<HTMLInputElement>` | — | Defines a callback handler that is called when user copies text to a clipboard (using a mouse or keyboard shortcut) |
| `onEnterPressed` | `KeyboardEventHandler<HTMLInputElement>` | — | Defines a callback handler that is called when the user presses -enter-. |
| `onEscapePressed` | `KeyboardEventHandler<HTMLInputElement>` | — | Defines a callback handler that is called when the user presses -escape-. |
| `onFocus` | `FocusEventHandler` | — | Defines a standard input onFocus callback. |
| `onInputClicked` | `MouseEventHandler` | — | Defines a standard input onClick callback. |
| `onKeyDown` | `KeyboardEventHandler<HTMLInputElement>` | — | Defines a standard input onKeyDown callback. |
| `onKeyUp` | `KeyboardEventHandler<HTMLInputElement>` | — | Defines a standard input onKeyUp callback. |
| `onPaste` | `ClipboardEventHandler<HTMLInputElement>` | — | Defines a callback handler that is called when user pastes text from a clipboard (using a mouse or keyboard shortcut) |
| `pattern` | `string` | — | Sets a pattern that typed value must match to be valid (regex) |
| `placeholder` | `string` | `''` | 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. |
| `popoverProps` | `Omit<PopoverNextProps, "children" \| "dataHook" \| "onClickOutside" \| "placement" \| "appendTo" \| "fixed" \| "showArrow" \| "shown" \| "open" \| "onOpenChange">` | — | Accepts popover props that are passed to the color picker popover. |
| `prefix` | `ReactNode` | — | Pass a component you want to show as the prefix of the input, e.g., text, icon. |
| `readOnly` | `boolean` | — | Specifies whether input is read only. |
| `ref` | `null \| 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). |
| `required` | `boolean` | — | Specifies whether input is mandatory. |
| `role` | `string` | — | Specifies the role of the input element for accessibility. |
| `rtl` | `boolean` | — | Specifies text direction. If true, the text is displayed from right to left. |
| `showDrawerOnMobile` | `boolean` | `true` | Specifies 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. |
| `statusMessage` | `ReactNode` | — | Defines the message to display on status icon hover. If not given or empty, no tooltip is displayed. |
| `statusMessageTooltipProps` | `TooltipCommonProps` | — | Status message tooltip props. |
| `step` | `number` | — | Specifies the interval between number values. |
| `suffix` | `ReactNode` | — | Pass a component you want to show as the suffix of the input, e.g., text, icon. |
| `tabIndex` | `number` | — | 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. |
| `type` | `string` | — | Specifies the type of `<input/>` element to display. Default is text. |
| `value` | `string` | `''` | Specifies the current value of the element. |
| `withSelection` | `boolean` | — |  |

## Testkit

Import the driver matching your test environment:

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

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

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

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

### Driver methods

| Method | Description |
| --- | --- |
| `cancel` | Cancels color selection |
| `confirm` | Confirms color selection |
| `clickColorViewer` | Clicks on color viewer box |
| `enterText` | Enters text to color input |
| `getValue` | Gets the input value |
| `getPlaceholder` | Gets the placeholder of the input |
| `getSize` | Gets the input size |
| `isDisabled` | Checks whether the input is disabled |
| `colorPickerVisible` | Checks whether the color picker is visible |
| `click` | Clicks on input |
| `hasStatus` | Checks whether the given status is displayed |
| `getStatusMessage` | Gets the status message |
| `exists` | Checks whether the component found with the given data hook. |
| `element` | Gets the component root element. |
| `base` | Returns 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](invalid-url))
- **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