---
title: ColorPicker
description: "`ColorPicker` is a component used by the user to select a color or enter an arbitrary color value."
links:
- source: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/components/color-picker
- storybook: https://yamada-ui.github.io/yamada-ui?path=/story/components-colorpicker--basic
---
```tsx
```
## Usage
```tsx
import { ColorPicker } from "@yamada-ui/react"
```
```tsx
import { ColorPicker } from "@/components/ui"
```
```tsx
import { ColorPicker } from "@workspaces/ui"
```
```tsx
```
### Change Variant
```tsx
{(variant, index) => (
)}
```
### Change Size
```tsx preview
{(size, index) => (
)}
```
### Change Color Scheme
```tsx
{(colorScheme, index) => (
)}
```
### Set Default Value
To set a default value, set `defaultValue` to a value.
```tsx
```
### 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.
```tsx
```
### 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`.
```tsx
```
### Limit Input Value
To limit the input value, set `pattern` to a regular expression.
```tsx
```
### Format Input Value
To format the input value, set `formatInput` to a function.
```tsx
value.toUpperCase()}
/>
```
### Show Color Swatches
To show color swatches, set `colorSwatches` to an array.
```tsx
```
### Change Color Swatch Columns
To change the number of columns in the color swatch group, set `colorSwatchGroupColumns` to a number.
```tsx
```
### Change Offset
To change the offset, set `gutter` or `offset` to a value.
```tsx
```
### Change Animation Scheme
To change the animation scheme, set `animationScheme` to `"block-start"` or `"inline-end"` etc. The default is `"scale"`.
```tsx
```
### Change Placement
To change the placement, set `placement` to `"end"` or `"start-center"` etc. The default is `"end-start"`.
```tsx
```
### Blocking Scroll
To block scrolling, set `blockScrollOnMount` to `true`.
```tsx
```
### Close Dropdown On Scroll
To close the dropdown on scroll, set `closeOnScroll` to `true`.
```tsx
```
### Handle Opening Dropdown On Change
To handle the event of opening the dropdown on change, set a function to `openOnChange`.
```tsx
ev.target.value.length > 1}
/>
```
### Handle Closing Dropdown On Change
To handle the event of closing the dropdown on change, set a function to `closeOnChange`.
```tsx
!ev.target.value.length}
/>
```
### Disable Open Dropdown On Focus
To disable opening the dropdown on focus, set `openOnFocus` to `false`.
```tsx
```
### Disable Open Dropdown On Click
To disable opening the dropdown on click, set `openOnClick` to `false`.
```tsx
```
### Disable Close On Outside Click
To disable closing the dropdown on outside click, set `closeOnBlur` to `false`.
```tsx
```
### Disable Close On Esc
To disable closing the dropdown on ESC key, set `closeOnEsc` to `false`.
```tsx
```
### Disable Allow Input
To disable allowing input, set `allowInput` to `false`.
```tsx
```
### Change Shape
```tsx
{(shape, index) => (
)}
```
### Disable
To disable, set `disabled` to `true`.
```tsx
{(variant, index) => (
)}
```
### Make Read Only
To make read only, set `readOnly` to `true`.
```tsx
{(variant, index) => (
)}
```
### Make Invalid
To make invalid, set `invalid` to `true`.
```tsx
{(variant, index) => (
)}
```
### Change Border Color
To change the border color, set `focusBorderColor` or `errorBorderColor` to a value.
```tsx
```
### Control
```tsx
const [value, onChange] = useState("#4387f4")
return
```
## 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) => 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> \| Iterable \| 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` | 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" \| "ActiveBorder" \| "ActiveCaption" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" \| "amber.400" \| "amber.50" \| "amber.500" ...` | 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" \| "ActiveBorder" \| "ActiveCaption" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" \| "amber.400" \| "amber.50" \| "amber.500" ...` | 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: Platform; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; elements: Elements; }) => Promisable<...>; } \| null \| undefined)[]` | 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` | Callback invoked to close the element. |
| `onInputChange` | - | `(ev: ChangeEvent) => void` | The callback invoked when input value state changes. |
| `onOpen` | - | `() => void \| Promise` | Callback invoked to open the element. |
| `open` | - | `boolean` | If `true`, the element will be opened. |
| `openOnChange` | `true` | `((ev: ChangeEvent) => 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
Currently, this section is being updated due to the migration of v2.