ColorPicker

ColorPicker is a component used by the user to select a color or enter an arbitrary color value.

<ColorPicker placeholder="#4387f4" />

Usage

import { ColorPicker } from "@yamada-ui/react"

import { ColorPicker } from "@/components/ui"

import { ColorPicker } from "@workspaces/ui"

<ColorPicker />

Change Variant

<VStack>
  <For each={["outline", "filled", "flushed", "plain"]}>
    {(variant, index) => (
      <ColorPicker
        key={index}
        variant={variant}
        placeholder={toTitleCase(variant)}
      />
    )}
  </For>
</VStack>

Change Size

<VStack>
  <For each={["xs", "sm", "md", "lg", "xl"]}>
    {(size, index) => (
      <ColorPicker key={index} size={size} placeholder={`Size (${size})`} />
    )}
  </For>
</VStack>

Change Color Scheme

<VStack>
  <For each={["success", "warning"]}>
    {(colorScheme, index) => (
      <ColorPicker
        key={index}
        colorScheme={colorScheme}
        placeholder="#4387f4"
      />
    )}
  </For>
</VStack>

Set Default Value

To set a default value, set defaultValue to a value.

<ColorPicker defaultValue="#4387f4" placeholder="#4387f4" />

Set Alpha Value

To set an alpha value, set defaultValue to a value containing an alpha value or set format to "hexa" or "hsla" etc.

<ColorPicker defaultValue="#775999A0" placeholder="#775999A0" />

Change Format

To change the format, set format to a value. The default is to determine the format from the string of value or defaultValue.

<ColorPicker placeholder="hsl(0, 100%, 50%)" format="hsl" />

Limit Input Value

To limit the input value, set pattern to a regular expression.

<ColorPicker placeholder="#4387f4" pattern={/[^a-fA-F0-9#]/g} />

Format Input Value

To format the input value, set formatInput to a function.

<ColorPicker
  placeholder="#4387f4"
  pattern={/[^a-fA-F0-9#]/g}
  formatInput={(value) => value.toUpperCase()}
/>

If you use this code, you need to add "use client" to the top of the file.

Show Color Swatches

To show color swatches, set colorSwatches to an array.

<ColorPicker
  placeholder="#4387f4"
  colorSwatches={[
    "hsl(0, 100%, 50%)",
    "hsl(45, 100%, 50%)",
    "hsl(90, 100%, 50%)",
    "hsl(135, 100%, 50%)",
    "hsl(180, 100%, 50%)",
    "hsl(225, 100%, 50%)",
    "hsl(270, 100%, 50%)",
    "hsl(315, 100%, 50%)",
  ]}
  colorSwatchGroupLabel="Pick a color"
/>

Change Color Swatch Columns

To change the number of columns in the color swatch group, set colorSwatchGroupColumns to a number.

<ColorPicker
  placeholder="#4387f4"
  colorSwatches={[
    "hsl(0, 100%, 50%)",
    "hsl(36, 100%, 50%)",
    "hsl(72, 100%, 50%)",
    "hsl(108, 100%, 50%)",
    "hsl(144, 100%, 50%)",
    "hsl(180, 100%, 50%)",
    "hsl(216, 100%, 50%)",
    "hsl(252, 100%, 50%)",
    "hsl(288, 100%, 50%)",
    "hsl(324, 100%, 50%)",
  ]}
  colorSwatchGroupLabel="Pick a color"
  colorSwatchGroupColumns={10}
/>

Change Offset

To change the offset, set gutter or offset to a value.

<ColorPicker placeholder="#4387f4" gutter={16} />

Change Animation Scheme

To change the animation scheme, set animationScheme to "block-start" or "inline-end" etc. The default is "scale".

<ColorPicker placeholder="#4387f4" animationScheme="inline-start" />

Change Placement

To change the placement, set placement to "end" or "start-center" etc. The default is "end-start".

<ColorPicker
  placeholder="#4387f4"
  animationScheme="inline-start"
  placement="center-end"
  rootProps={{ w: "xs" }}
/>

Blocking Scroll

To block scrolling, set blockScrollOnMount to true.

<ColorPicker placeholder="#4387f4" blockScrollOnMount />

To close the dropdown on scroll, set closeOnScroll to true.

<ColorPicker placeholder="#4387f4" closeOnScroll />

To handle the event of opening the dropdown on change, set a function to openOnChange.

<ColorPicker
  placeholder="#4387f4"
  openOnFocus={false}
  openOnChange={(ev) => ev.target.value.length > 1}
/>

If you use this code, you need to add "use client" to the top of the file.

To handle the event of closing the dropdown on change, set a function to closeOnChange.

<ColorPicker
  placeholder="#4387f4"
  openOnFocus={false}
  closeOnChange={(ev) => !ev.target.value.length}
/>

If you use this code, you need to add "use client" to the top of the file.

To disable opening the dropdown on focus, set openOnFocus to false.

<ColorPicker placeholder="#4387f4" openOnFocus={false} />

To disable opening the dropdown on click, set openOnClick to false.

<ColorPicker placeholder="#4387f4" openOnClick={false} />

Disable Close On Outside Click

To disable closing the dropdown on outside click, set closeOnBlur to false.

<ColorPicker placeholder="#4387f4" closeOnBlur={false} />

Disable Close On Esc

To disable closing the dropdown on ESC key, set closeOnEsc to false.

<ColorPicker placeholder="#4387f4" closeOnEsc={false} />

Disable Allow Input

To disable allowing input, set allowInput to false.

<ColorPicker placeholder="#4387f4" allowInput={false} />

Change Shape

<VStack>
  <For each={["rounded", "circle", "square"]}>
    {(shape, index) => (
      <ColorPicker
        key={index}
        placeholder="#4387f4"
        selectorProps={{ shape }}
      />
    )}
  </For>
</VStack>

Disable

To disable, set disabled to true.

<VStack>
  <For each={["outline", "filled", "flushed"]}>
    {(variant, index) => (
      <ColorPicker
        key={index}
        variant={variant}
        disabled
        placeholder={toTitleCase(variant)}
      />
    )}
  </For>
</VStack>

Make Read Only

To make read only, set readOnly to true.

<VStack>
  <For each={["outline", "filled", "flushed"]}>
    {(variant, index) => (
      <ColorPicker
        key={index}
        variant={variant}
        readOnly
        placeholder={toTitleCase(variant)}
      />
    )}
  </For>
</VStack>

Make Invalid

To make invalid, set invalid to true.

<VStack>
  <For each={["outline", "filled", "flushed"]}>
    {(variant, index) => (
      <ColorPicker
        key={index}
        variant={variant}
        invalid
        placeholder={toTitleCase(variant)}
      />
    )}
  </For>
</VStack>

Change Border Color

To change the border color, set focusBorderColor or errorBorderColor to a value.

<VStack>
  <ColorPicker focusBorderColor="green.500" placeholder="custom border color" />
  <ColorPicker
    invalid
    errorBorderColor="orange.500"
    placeholder="custom border color"
  />
</VStack>

Control

const [value, onChange] = useState<string>("#4387f4")

return <ColorPicker value={value} onChange={onChange} />

Props

Prop	Default	Type / Description
`as`	-	`As` The HTML element to render.
`asChild`	-	`boolean` Merges its props onto its immediate child.
`css`	-	`CSSObject \| CSSObject[]` The CSS object.
`colorScheme`	-	`"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` Set color scheme variables.
`size`	`"md"`	`"lg" \| "md" \| "sm" \| "xl" \| "xs"` The size of the component.
`variant`	`"outline"`	`"filled" \| "flushed" \| "outline" \| "plain"` The variant of the component.
`allowInput`	`true`	`boolean` If `true`, allows input.
`alphaSliderProps`	-	`ColorSelectorAlphaSliderProps` Props for the alpha slider.
`animationScheme`	`"scale"`	`"none" \| "scale" \| SimplePlacement` The animation of the element.
`autoUpdate`	`true`	`boolean` If `true`, automatically updates the position of the floating element when necessary.
`blockScrollOnMount`	`false`	`boolean` If `true`, scrolling will be disabled on the `body` when the modal opens.
`closeOnBlur`	`true`	`boolean` If `true`, the popover will close when you blur out it by clicking outside or tabbing out.
`closeOnChange`	`false`	`((ev: ChangeEvent<HTMLInputElement>) => boolean) \| boolean` If `true`, the color picker will be closed when the input value changes.
`closeOnEsc`	`true`	`boolean` If `true`, the popover will hide on pressing Esc key.
`closeOnScroll`	`false`	`boolean` If `true`, the popover will hide on scroll.
`colorSwatches`	-	`string[]` An array of colors in one of the supported formats. Used to render swatches list below the color selector.
`colorSwatchGroupColumns`	`8`	`number` The number of columns in the color swatch group.
`colorSwatchGroupLabel`	-	`string \| number \| bigint \| boolean \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal \| Promise<...>` The label of the color swatch group.
`colorSwatchGroupLabelProps`	-	`ColorSelectorColorSwatchGroupLabelProps` Props for the color swatch group label.
`colorSwatchGroupProps`	-	`ColorSelectorColorSwatchGroupProps` Props for the color swatch group.
`colorSwatchItemProps`	-	`Omit<ColorSelectorColorSwatchItemProps, "value">` Props for the color swatch item.
`colorSwatchProps`	-	`ColorPickerColorSwatchProps` Props for the color swatch component.
`contentProps`	-	`ColorPickerContentProps` Props for content element.
`defaultOpen`	-	`boolean` If `true`, the element will be initially opened.
`defaultValue`	-	`string` The initial value of the color picker.
`disabled`	`false`	`boolean` If `true`, the combobox will be disabled.
`duration`	`0.2`	`MotionTransitionProps["duration"]` The animation duration.
`elementProps`	-	`InputGroup.ElementProps` The props for the input element.
`elements`	-	`{ floating?: HTMLElement \| null \| undefined; reference?: HTMLButtonElement \| null \| undefined }` Object containing the reference and floating elements.
`endElementProps`	-	`InputGroup.ElementProps` The props for the end element.
`errorBorderColor`	-	`"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` The border color when the input is invalid.
`eyeDropperProps`	-	`ColorPickerEyeDropperProps` Props for the eye dropper component.
`fallbackValue`	`"#FFFFFF"`	`string` The fallback value of the color picker.
`fieldProps`	-	`ColorPickerFieldProps` The props for the field component.
`flip`	`true`	`boolean` If `true`, the popper will change its placement and flip when it's about to overflow its boundary area.
`focusBorderColor`	-	`"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` The border color when the input is focused.
`format`	`"hex"`	`ColorFormat` The format of the color picker. Automatically determines the format of `value` or `defaultValue`.
`formatInput`	-	`(value: string) => string` The function to format the input value.
`gutter`	`8`	`number` The distance or margin between the reference and popper. It is used internally to create an `offset` modifier.
`hueSliderProps`	-	`ColorSelectorHueSliderProps` Props for the hue slider.
`inputProps`	-	`HTMLStyledProps<"input">` The props for the input element.
`invalid`	`false`	`boolean` If `true`, the field will be invalid.
`matchWidth`	`false`	`boolean` If `true`, the popper will match the width of the reference at all times. It's useful for `autocomplete`, `date-picker` and `select` patterns.
`middleware`	-	`(false \| { name: string; options?: any; fn: (state: { x: number; y: number; placement: Placement; platform: { detectOverflow: (state: MiddlewareState, options?: DetectOverflowOptions \| Derivable<...> \| undefined) => Promise<...>; } & Platform; ... 4 more ...; elements: Elements; }) => Promisable<...>; } \| null \| und...` Array of middleware objects to modify the positioning or provide data for rendering.
`name`	-	`string` The `name` attribute of the input element.
`offset`	-	`[number, number]` The main and cross-axis offset to displace popper element from its reference element.
`onChange`	-	`(value: string) => void` The callback invoked when the value changes.
`onClose`	-	`() => void \| Promise<void>` Callback invoked to close the element.
`onInputChange`	-	`(ev: ChangeEvent<HTMLInputElement>) => void` The callback invoked when input value state changes.
`onOpen`	-	`() => void \| Promise<void>` Callback invoked to open the element.
`open`	-	`boolean` If `true`, the element will be opened.
`openOnChange`	`true`	`((ev: ChangeEvent<HTMLInputElement>) => boolean) \| boolean` If `true`, the color picker will be opened when the input value changes.
`openOnClick`	`true`	`boolean` If `true`, the combobox will be opened when click on the field.
`openOnEnter`	`true`	`boolean` If `true`, the combobox will be opened when enter is pressed.
`openOnFocus`	`false`	`boolean` If `true`, the color picker will be opened when the input is focused.
`openOnSpace`	`true`	`boolean` If `true`, the combobox will be opened when space is pressed.
`pattern`	-	`RegExp` The pattern used to check the input element.
`placeholder`	-	`string` The placeholder for color picker.
`placement`	`"end-start"`	`Direction` The placement of the popper relative to its reference.
`platform`	-	`Platform` Custom or extended platform object.
`preventOverflow`	`true`	`boolean` If `true`, will prevent the popper from being cut off and ensure it's visible within the boundary area.
`readOnly`	`false`	`boolean` If `true`, the combobox will be readonly.
`required`	`false`	`boolean` If `true`, the field will be required.
`rootProps`	-	`InputGroup.RootProps` Props for root element.
`saturationSliderProps`	-	`ColorSelectorSaturationSliderProps` Props for the saturation slider.
`selectorProps`	-	`ColorSelector.RootProps` Props for the selector component.
`startElementProps`	-	`InputGroup.ElementProps` The props for the start element.
`strategy`	`"absolute"`	`Strategy` The CSS positioning strategy to use.
`transferFocus`	`true`	`boolean` If `true`, the focus will be transferred to the popover content when the tab key is pressed.
`value`	-	`string` The value of the color picker.
`whileElementsMounted`	-	`(reference: HTMLButtonElement, floating: HTMLElement, update: () => void) => () => void` A callback invoked when both the reference and floating elements are mounted, and cleaned up when either is unmounted. This is useful for setting up event listeners (e.g. pass `autoUpdate`).
`withColorSwatch`	`true`	`boolean` If `true`, the color swatch component will be displayed.
`withEyeDropper`	`true`	`boolean` If `true`, the eye dropper component will be displayed.

Accessibility

ColorPicker follows the WAI-ARIA - Combobox Pattern for accessibility.

If you do not use Field.Root, set aria-label or aria-labelledby on ColorPicker.

<ColorPicker placeholder="#4387f4" aria-label="Pick color" />

<VStack gap="sm">
  <Text as="h3" id="label">
    Pick Color
  </Text>

  <ColorPicker placeholder="#4387f4" aria-labelledby="label" />
</VStack>

Key	Description	State
`Tab`	Opens the dialog when focus moves to the color picker.	`openOnFocus={true}`
`Escape`	Closes the dialog.	`closeOnEsc={true}`
`ArrowRight`, `ArrowUp`	If within a slider, increases the value based on `step`.	-
`ArrowLeft`, `ArrowDown`	If within a slider, decreases the value based on `step`.	-
`Home`	If within hue slider or alpha slider, sets the value to `min`.	-
`End`	If within hue slider or alpha slider, sets the value to `max`.	-
`PageUp`	If within hue slider or alpha slider, increases the value based on `min` and `max`.	-
`PageDown`	If within hue slider or alpha slider, decreases the value based on `min` and `max`.	-

ARIA Roles and Attributes

Component and Element	Roles and Attributes	Usage
`div.ui-color-picker__field`	`role="combobox"`	Indicates that this is a combobox.
	`aria-controls`	If the dialog is open, sets the `id` of the related `div.ui-color-picker__content` when closed, sets `undefined`.
	`aria-describedby`	If this is within a `Field.Root` and `Field.Root` has an `errorMessage`, `helperMessage`, or a `Field.ErrorMessage`, `Field.HelperMessage`, sets its `id`.
	`aria-disabled`	Sets to `"true"` if `disabled` or `readOnly` is set.
	`aria-expanded`	Sets to `"true"` when the dialog is open, `"false"` when closed.
	`aria-haspopup="dialog"`	Indicates that a dialog exists.
	`aria-invalid`	Sets to `"true"` if `invalid` is set.
	`aria-readonly`	Sets to `"true"` if `readOnly` is set.
	`aria-required`	Sets to `"true"` if `required` is set.
`div.ui-color-picker__eye-dropper`	`role="button"`	Indicates that this is a button.
	`aria-disabled`	Sets to `"true"` if `disabled` or `readOnly` is set.
	`aria-label`	Sets to `"Pick a color"`.
`div.ui-color-picker__content`	`role="dialog"`	Indicates that this is a dialog.
`div.ui-color-selector__saturation-slider > input`	`aria-hidden`	Excludes the element from the accessibility tree.
	`aria-describedby`	If this is within a `Field.Root` and `Field.Root` has an `errorMessage`, `helperMessage`, or a `Field.ErrorMessage`, `Field.HelperMessage`, sets its `id`.
`div.ui-color-selector__saturation-slider > div`	`role="slider"`	Indicates that this is a slider.
	`aria-label`	Sets to `"Saturation and brightness thumb"`.
	`aria-describedby`	If this is within a `Field.Root` and `Field.Root` has an `errorMessage`, `helperMessage`, or a `Field.ErrorMessage`, `Field.HelperMessage`, sets its `id`.
	`aria-roledescription`	Sets to `"2D slider"`.
	`aria-valuemin`	Sets the value of `min`. The default is `0`.
	`aria-valuemax`	Sets the value of `max`. The default is `100`.
	`aria-valuenow`	Sets the current value.
	`aria-valuetext`	Sets the current value like `"Saturation 18%, Brightness 18%"`.
`div.ui-color-selector__hue-slider > input`	`aria-hidden`	Excludes the element from the accessibility tree.
	`aria-describedby`	If this is within a `Field.Root` and `Field.Root` has an `errorMessage`, `helperMessage`, or a `Field.ErrorMessage`, `Field.HelperMessage`, sets its `id`.
`div.ui-color-selector__hue-slider > div`	`role="slider"`	Indicates that this is a slider.
	`aria-label`	Sets to `"Slider thumb"`.
	`aria-describedby`	If this is within a `Field.Root` and `Field.Root` has an `errorMessage`, `helperMessage`, or a `Field.ErrorMessage`, `Field.HelperMessage`, sets its `id`.
	`aria-orientation`	Sets to `"horizontal"` or `"vertical"` based on `orientation`. The default is `"horizontal"`.
	`aria-valuemin`	Sets the value of `min`. The default is `0`.
	`aria-valuemax`	Sets the value of `max`. The default is `360`.
	`aria-valuenow`	Sets the current value.
	`aria-valuetext`	Sets the current value like `"18°, Red"`.
`div.ui-color-selector__alpha-slider > input`	`aria-hidden`	Excludes the element from the accessibility tree.
	`aria-describedby`	If this is within a `Field.Root` and `Field.Root` has an `errorMessage`, `helperMessage`, or a `Field.ErrorMessage`, `Field.HelperMessage`, sets its `id`.
`div.ui-color-selector__alpha-slider > div`	`role="slider"`	Indicates that this is a slider.
	`aria-label`	Sets to `"Slider thumb"`.
	`aria-describedby`	If this is within a `Field.Root` and `Field.Root` has an `errorMessage`, `helperMessage`, or a `Field.ErrorMessage`, `Field.HelperMessage`, sets its `id`.
	`aria-orientation`	Sets to `"horizontal"` or `"vertical"` based on `orientation`. The default is `"horizontal"`.
	`aria-valuemin`	Sets the value of `min`. The default is `0`.
	`aria-valuemax`	Sets the value of `max`. The default is `1`.
	`aria-valuenow`	Sets the current value.
	`aria-valuetext`	Sets the current value like `"18%"`.
`span.ui-color-selector__color-swatch-group-label`	`id`	Used to associate with `div.ui-color-selector__color-swatch-group`.
`div.ui-color-selector__color-swatch-group`	`role="listbox"`	Indicates that this is a listbox.
	`aria-labelledby`	Sets the `id` of the associated `span.ui-color-selector__color-swatch-group-label`.
`div.ui-color-selector__color-swatch-item`	`role="option"`	Indicates that this is an option.
	`aria-label`	Sets the current value.
	`aria-roledescription`	Sets to `"color swatch"`.
	`aria-selected`	Sets to `"true"` if `value` is the same as the current value.

Similar Components

ColorSelector is a component used by the user to select a color.

AlphaSlider is a component used to allow the user to select color transparency.

DatePicker is a component used for users to select a date.

HueSlider is a component used to allow the user to select a color hue.

SaturationSlider is a component used to allow the user to select a color saturation.

Select is a component used for allowing a user to choose values from a list of options.

Uses Components & Hooks

DatePicker is a component used for users to select a date.

NativeSelect is a component used for allowing users to select one value from a list of options. It displays a native dropdown list provided by the browser (user agent).

ColorSwatch is a component that displays color samples.

Input is a component used to obtain text input from the user.

Popover is a component that floats around an element to display information.

ColorSelector is a component used by the user to select a color.

Group is a component that groups and attaches multiple elements together.

Icon is a general icon component that can be used in your projects.

Field is a component used to group form elements with label, helper message, error message, etc.

useEyeDropper is a custom hook that opens the eye dropper tool and returns the color value.