Color Picker

A component that allows users to select a color from a color picker.

Color Picker

Anatomy

<ColorPicker.Root>
  <ColorPicker.Label />
  <ColorPicker.Control>
    <ColorPicker.ChannelInput />
    <ColorPicker.Trigger>
      <ColorPicker.ValueSwatch />
    </ColorPicker.Trigger>
  </ColorPicker.Control>
  <ColorPicker.Positioner>
    <ColorPicker.Content>
      <ColorPicker.Area>
        <ColorPicker.AreaBackground />
        <ColorPicker.AreaThumb />
      </ColorPicker.Area>
      <ColorPicker.EyeDropperTrigger />
      <ColorPicker.ChannelSlider>
        <ColorPicker.ChannelSliderTrack />
        <ColorPicker.ChannelSliderThumb />
      </ColorPicker.ChannelSlider>
      <ColorPicker.SwatchGroup>
        <ColorPicker.SwatchTrigger>
          <ColorPicker.Swatch />
        </ColorPicker.SwatchTrigger>
      </ColorPicker.SwatchGroup>
    </ColorPicker.Content>
  </ColorPicker.Positioner>
  <ColorPicker.HiddenInput />
</ColorPicker.Root>

Examples

Controlled

Use the value and onValueChange props to programatically control the color picker's state.

Open Controlled

Control the open state of the color picker popover programmatically using the open and onOpenChange props.

Root Provider

An alternative way to control the color picker is to use the RootProvider component and the useColorPicker hook. This way you can access the state and methods from outside the component.

Disabled

Use the disabled prop to disable the color picker.

Inline

Render the color picker inline without a popover by using the inline prop.

Input Only

A minimal color picker with just an input field, value swatch, and eye dropper trigger.

Slider Only

Display only the channel sliders for RGB color selection.

Swatch Only

A simple color picker with only preset color swatches.

Swatches

Include preset color swatches in the color picker content for quick color selection.

Value Swatch

Display the current color value as a swatch alongside the color area and sliders.

Field

The Field component helps manage form-related state and accessibility attributes of a color picker. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility.

Form Usage

Integrate the color picker with form libraries like React Hook Form using the HiddenInput component.

API Reference

Props

Root

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`closeOnSelect`	`false`	`boolean` Whether to close the color picker when a swatch is selected
`defaultFormat`	`'rgba'`	`ColorFormat` The initial color format when rendered. Use when you don't need to control the color format of the color picker.
`defaultOpen`		`boolean` The initial open state of the color picker when rendered. Use when you don't need to control the open state of the color picker.
`defaultValue`	`#000000`	`Color` The initial color value when rendered. Use when you don't need to control the color value of the color picker.
`disabled`		`boolean` Whether the color picker is disabled
`format`		`ColorFormat` The controlled color format to use
`id`		`string` The unique identifier of the machine.
`ids`		`Partial<{ root: string; control: string; trigger: string; label: string; input: string; hiddenInput: string; content: string; area: string; areaGradient: string; positioner: string; formatSelect: string; areaThumb: string; channelInput: (id: string) => string; channelSliderTrack: (id: ColorChannel) => string; channe...` The ids of the elements in the color picker. Useful for composition.
`immediate`		`boolean` Whether to synchronize the present change immediately or defer it to the next frame
`initialFocusEl`		`() => HTMLElement \| null` The initial focus element when the color picker is opened.
`inline`		`boolean` Whether to render the color picker inline
`invalid`		`boolean` Whether the color picker is invalid
`lazyMount`	`false`	`boolean` Whether to enable lazy mounting
`name`		`string` The name for the form input
`onExitComplete`		`VoidFunction` Function called when the animation ends in the closed state
`onFocusOutside`		`(event: FocusOutsideEvent) => void` Function called when the focus is moved outside the component
`onFormatChange`		`(details: FormatChangeDetails) => void` Function called when the color format changes
`onInteractOutside`		`(event: InteractOutsideEvent) => void` Function called when an interaction happens outside the component
`onOpenChange`		`(details: OpenChangeDetails) => void` Handler that is called when the user opens or closes the color picker.
`onPointerDownOutside`		`(event: PointerDownOutsideEvent) => void` Function called when the pointer is pressed down outside the component
`onValueChange`		`(details: ValueChangeDetails) => void` Handler that is called when the value changes, as the user drags.
`onValueChangeEnd`		`(details: ValueChangeDetails) => void` Handler that is called when the user stops dragging.
`open`		`boolean` The controlled open state of the color picker
`openAutoFocus`	`true`	`boolean` Whether to auto focus the color picker when it is opened
`positioning`		`PositioningOptions` The positioning options for the color picker
`present`		`boolean` Whether the node is present (controlled by the user)
`readOnly`		`boolean` Whether the color picker is read-only
`required`		`boolean` Whether the color picker is required
`skipAnimationOnMount`	`false`	`boolean` Whether to allow the initial presence animation.
`unmountOnExit`	`false`	`boolean` Whether to unmount on exit.
`value`		`Color` The controlled color value of the color picker

Attribute	Description
`[data-scope]`	color-picker
`[data-part]`	root
`[data-disabled]`	Present when disabled
`[data-readonly]`	Present when read-only
`[data-invalid]`	Present when invalid

CSS Variable	Description
`--value`	The current value

AreaBackground

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	color-picker
`[data-part]`	area-background
`[data-invalid]`	Present when invalid
`[data-disabled]`	Present when disabled
`[data-readonly]`	Present when read-only

Area

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`xChannel`		`ColorChannel`
`yChannel`		`ColorChannel`

Attribute	Description
`[data-scope]`	color-picker
`[data-part]`	area
`[data-invalid]`	Present when invalid
`[data-disabled]`	Present when disabled
`[data-readonly]`	Present when read-only

AreaThumb

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	color-picker
`[data-part]`	area-thumb
`[data-disabled]`	Present when disabled
`[data-invalid]`	Present when invalid
`[data-readonly]`	Present when read-only

CSS Variable	Description
`--color`	The text color

ChannelInput

Renders a <input> element.

Prop	Default	Type
`channel`		`ExtendedColorChannel`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`orientation`		`Orientation`

Attribute	Description
`[data-scope]`	color-picker
`[data-part]`	channel-input
`[data-channel]`	The color channel of the channelinput
`[data-disabled]`	Present when disabled
`[data-invalid]`	Present when invalid
`[data-readonly]`	Present when read-only

ChannelSliderLabel

Renders a <label> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	color-picker
`[data-part]`	channel-slider-label
`[data-channel]`	The color channel of the channelsliderlabel

ChannelSlider

Renders a <div> element.

Prop	Default	Type
`channel`		`ColorChannel`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`orientation`		`Orientation`

Attribute	Description
`[data-scope]`	color-picker
`[data-part]`	channel-slider
`[data-channel]`	The color channel of the channelslider
`[data-orientation]`	The orientation of the channelslider

ChannelSliderThumb

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	color-picker
`[data-part]`	channel-slider-thumb
`[data-channel]`	The color channel of the channelsliderthumb
`[data-disabled]`	Present when disabled
`[data-orientation]`	The orientation of the channelsliderthumb

ChannelSliderTrack

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	color-picker
`[data-part]`	channel-slider-track
`[data-channel]`	The color channel of the channelslidertrack
`[data-orientation]`	The orientation of the channelslidertrack

ChannelSliderValueText

Renders a <span> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	color-picker
`[data-part]`	channel-slider-value-text
`[data-channel]`	The color channel of the channelslidervaluetext

Content

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	color-picker
`[data-part]`	content
`[data-placement]`	The placement of the content
`[data-nested]`	popover
`[data-has-nested]`	popover
`[data-state]`	"open" \| "closed"

CSS Variable	Description
`--layer-index`	The index of the dismissable in the layer stack
`--nested-layer-count`	The number of nested color-pickers

Control

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	color-picker
`[data-part]`	control
`[data-disabled]`	Present when disabled
`[data-readonly]`	Present when read-only
`[data-invalid]`	Present when invalid
`[data-state]`	"open" \| "closed"
`[data-focus]`	Present when focused

EyeDropperTrigger

Renders a <button> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	color-picker
`[data-part]`	eye-dropper-trigger
`[data-disabled]`	Present when disabled
`[data-invalid]`	Present when invalid
`[data-readonly]`	Present when read-only

FormatSelect

Renders a <select> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

FormatTrigger

Renders a <button> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

HiddenInput

Renders a <input> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Label

Renders a <label> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	color-picker
`[data-part]`	label
`[data-disabled]`	Present when disabled
`[data-readonly]`	Present when read-only
`[data-invalid]`	Present when invalid
`[data-required]`	Present when required
`[data-focus]`	Present when focused

Positioner

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

CSS Variable	Description
`--reference-width`	The width of the reference element
`--reference-height`	The height of the root
`--available-width`	The available width in viewport
`--available-height`	The available height in viewport
`--x`	The x position for transform
`--y`	The y position for transform
`--z-index`	The z-index value
`--transform-origin`	The transform origin for animations

RootProvider

Renders a <div> element.

Prop	Default	Type
`value`		`UseColorPickerReturn`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`immediate`		`boolean` Whether to synchronize the present change immediately or defer it to the next frame
`lazyMount`	`false`	`boolean` Whether to enable lazy mounting
`onExitComplete`		`VoidFunction` Function called when the animation ends in the closed state
`present`		`boolean` Whether the node is present (controlled by the user)
`skipAnimationOnMount`	`false`	`boolean` Whether to allow the initial presence animation.
`unmountOnExit`	`false`	`boolean` Whether to unmount on exit.

SwatchGroup

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

SwatchIndicator

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Swatch

Renders a <div> element.

Prop	Default	Type
`value`		`string \| Color` The color value
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`respectAlpha`		`boolean` Whether to include the alpha channel in the color

Attribute	Description
`[data-scope]`	color-picker
`[data-part]`	swatch
`[data-state]`	"checked" \| "unchecked"
`[data-value]`	The value of the item

CSS Variable	Description
`--color`	The text color

SwatchTrigger

Renders a <button> element.

Prop	Default	Type
`value`		`string \| Color` The color value
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`disabled`		`boolean` Whether the swatch trigger is disabled

Attribute	Description
`[data-scope]`	color-picker
`[data-part]`	swatch-trigger
`[data-state]`	"checked" \| "unchecked"
`[data-value]`	The value of the item
`[data-disabled]`	Present when disabled

CSS Variable	Description
`--color`	The text color

TransparencyGrid

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`size`		`string`

CSS Variable	Description
`--size`	The size (width and height) of the element

Trigger

Renders a <button> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	color-picker
`[data-part]`	trigger
`[data-disabled]`	Present when disabled
`[data-readonly]`	Present when read-only
`[data-invalid]`	Present when invalid
`[data-placement]`	The placement of the trigger
`[data-state]`	"open" \| "closed"
`[data-focus]`	Present when focused

ValueSwatch

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`respectAlpha`		`boolean` Whether to include the alpha channel in the color

ValueText

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`format`		`ColorStringFormat`

Attribute	Description
`[data-scope]`	color-picker
`[data-part]`	value-text
`[data-disabled]`	Present when disabled
`[data-focus]`	Present when focused

View

Renders a <div> element.

Prop	Default	Type
`format`		`ColorFormat`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Context

API

Property	Type
`dragging`	`boolean` Whether the color picker is being dragged
`open`	`boolean` Whether the color picker is open
`inline`	`boolean` Whether the color picker is rendered inline
`value`	`Color` The current color value (as a string)
`valueAsString`	`string` The current color value (as a Color object)
`setValue`	`(value: string \| Color) => void` Function to set the color value
`getChannelValue`	`(channel: ColorChannel) => string` Function to set the color value
`getChannelValueText`	`(channel: ColorChannel, locale: string) => string` Function to get the formatted and localized value of a specific channel
`setChannelValue`	`(channel: ColorChannel, value: number) => void` Function to set the color value of a specific channel
`format`	`ColorFormat` The current color format
`setFormat`	`(format: ColorFormat) => void` Function to set the color format
`alpha`	`number` The alpha value of the color
`setAlpha`	`(value: number) => void` Function to set the color alpha
`setOpen`	`(open: boolean) => void` Function to open or close the color picker

Accessibility

Keyboard Support

Key	Description
`Enter`	When focus is on the trigger, opens the color picker When focus is on a trigger of a swatch, selects the color (and closes the color picker) When focus is on the input or channel inputs, selects the color
`ArrowLeft`	When focus is on the color area, decreases the hue value of the color When focus is on the channel sliders, decreases the value of the channel
`ArrowRight`	When focus is on the color area, increases the hue value of the color When focus is on the channel sliders, increases the value of the channel
`ArrowUp`	When focus is on the color area, increases the saturation value of the color When focus is on the channel sliders, increases the value of the channel
`ArrowDown`	When focus is on the color area, decreases the saturation value of the color When focus is on the channel sliders, decreases the value of the channel
`Esc`	Closes the color picker and moves focus to the trigger