Components
Color picker

Color Picker

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

Anatomy

To set up the color picker correctly, you'll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Examples

Learn how to use the ColorPicker component in your project. Let's take a look at the most basic example

import { ColorPicker, parseColor } from '@ark-ui/react/color-picker'

export const Basic = () => {
  return (
    <ColorPicker.Root defaultValue={parseColor('#eb5e41')}>
      <ColorPicker.Label>Color</ColorPicker.Label>
      <ColorPicker.Control>
        <ColorPicker.ChannelInput channel="hex" />
        <ColorPicker.ChannelInput channel="alpha" />
        <ColorPicker.ValueText />
        <ColorPicker.Trigger>
          <ColorPicker.TransparencyGrid />
          <ColorPicker.ValueSwatch />
        </ColorPicker.Trigger>
      </ColorPicker.Control>
      <ColorPicker.Positioner>
        <ColorPicker.Content>
          <ColorPicker.FormatTrigger>Toggle ColorFormat</ColorPicker.FormatTrigger>
          <ColorPicker.FormatSelect />
          <ColorPicker.Area>
            <ColorPicker.AreaBackground />
            <ColorPicker.AreaThumb />
          </ColorPicker.Area>
          <ColorPicker.ChannelSlider channel="hue">
            <ColorPicker.ChannelSliderTrack />
            <ColorPicker.ChannelSliderThumb />
          </ColorPicker.ChannelSlider>
          <ColorPicker.ChannelSlider channel="alpha">
            <ColorPicker.TransparencyGrid />
            <ColorPicker.ChannelSliderTrack />
            <ColorPicker.ChannelSliderThumb />
          </ColorPicker.ChannelSlider>
          <ColorPicker.SwatchGroup>
            <ColorPicker.SwatchTrigger value="red">
              <ColorPicker.Swatch value="red">
                <ColorPicker.SwatchIndicator>✓</ColorPicker.SwatchIndicator>
              </ColorPicker.Swatch>
            </ColorPicker.SwatchTrigger>
            <ColorPicker.SwatchTrigger value="blue">
              <ColorPicker.Swatch value="blue">
                <ColorPicker.SwatchIndicator>✓</ColorPicker.SwatchIndicator>
              </ColorPicker.Swatch>
            </ColorPicker.SwatchTrigger>
            <ColorPicker.SwatchTrigger value="green">
              <ColorPicker.Swatch value="green">
                <ColorPicker.SwatchIndicator>✓</ColorPicker.SwatchIndicator>
              </ColorPicker.Swatch>
            </ColorPicker.SwatchTrigger>
          </ColorPicker.SwatchGroup>
          <ColorPicker.View format="rgba">
            <ColorPicker.ChannelInput channel="hex" />
            <ColorPicker.ChannelInput channel="alpha" />
          </ColorPicker.View>
          <ColorPicker.View format="hsla">
            <ColorPicker.ChannelInput channel="hue" />
            <ColorPicker.ChannelInput channel="saturation" />
            <ColorPicker.ChannelInput channel="lightness" />
          </ColorPicker.View>
          <ColorPicker.EyeDropperTrigger>Pick color</ColorPicker.EyeDropperTrigger>
        </ColorPicker.Content>
      </ColorPicker.Positioner>
      <ColorPicker.HiddenInput />
    </ColorPicker.Root>
  )
}

Controlled Color Picker

To create a controlled Color Picker component, manage the state of the current color using the value prop and update it when the onValueChange or onValueChangeEnd event handler is called:

import { ColorPicker, parseColor } from '@ark-ui/react/color-picker'
import { useState } from 'react'

export const Controlled = () => {
  const [color, setColor] = useState(() => parseColor('hsl(20, 100%, 50%)'))

  return (
    <ColorPicker.Root format="hsla" value={color} onValueChange={(e) => setColor(e.value)}>
      <ColorPicker.Label>Color</ColorPicker.Label>
      <ColorPicker.Control>
        <ColorPicker.ChannelInput channel="hex" />
        <ColorPicker.ChannelInput channel="alpha" />
        <ColorPicker.ValueText />
        <ColorPicker.Trigger>
          <ColorPicker.TransparencyGrid />
          <ColorPicker.ValueSwatch />
        </ColorPicker.Trigger>
      </ColorPicker.Control>

      <ColorPicker.Positioner>
        <ColorPicker.Content>
          <ColorPicker.Area>
            <ColorPicker.AreaBackground />
            <ColorPicker.AreaThumb />
          </ColorPicker.Area>

          <ColorPicker.ChannelSlider channel="hue">
            <ColorPicker.ChannelSliderTrack />
            <ColorPicker.ChannelSliderThumb />
          </ColorPicker.ChannelSlider>
          <ColorPicker.ChannelSlider channel="alpha">
            <ColorPicker.TransparencyGrid />
            <ColorPicker.ChannelSliderTrack />
            <ColorPicker.ChannelSliderThumb />
          </ColorPicker.ChannelSlider>

          <ColorPicker.SwatchGroup>
            <ColorPicker.SwatchTrigger value="red">
              <ColorPicker.Swatch value="red">
                <ColorPicker.SwatchIndicator>✓</ColorPicker.SwatchIndicator>
              </ColorPicker.Swatch>
            </ColorPicker.SwatchTrigger>
            <ColorPicker.SwatchTrigger value="blue">
              <ColorPicker.Swatch value="blue">
                <ColorPicker.SwatchIndicator>✓</ColorPicker.SwatchIndicator>
              </ColorPicker.Swatch>
            </ColorPicker.SwatchTrigger>
            <ColorPicker.SwatchTrigger value="green">
              <ColorPicker.Swatch value="green">
                <ColorPicker.SwatchIndicator>✓</ColorPicker.SwatchIndicator>
              </ColorPicker.Swatch>
            </ColorPicker.SwatchTrigger>
          </ColorPicker.SwatchGroup>

          <ColorPicker.View format="rgba">
            <ColorPicker.ChannelInput channel="hex" />
            <ColorPicker.ChannelInput channel="alpha" />
          </ColorPicker.View>

          <ColorPicker.View format="hsla">
            <ColorPicker.ChannelInput channel="hue" />
            <ColorPicker.ChannelInput channel="saturation" />
            <ColorPicker.ChannelInput channel="lightness" />
          </ColorPicker.View>

          <ColorPicker.EyeDropperTrigger>Pick color</ColorPicker.EyeDropperTrigger>
        </ColorPicker.Content>
      </ColorPicker.Positioner>

      <ColorPicker.HiddenInput />
    </ColorPicker.Root>
  )
}

Using the Field Component

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.

import { ColorPicker, parseColor } from '@ark-ui/react/color-picker'
import { Field } from '@ark-ui/react/field'

export const WithField = (props: Field.RootProps) => (
  <Field.Root {...props}>
    <ColorPicker.Root defaultValue={parseColor('#eb5e41')}>
      <ColorPicker.Label>Label</ColorPicker.Label>
      <ColorPicker.Control>
        <ColorPicker.ChannelInput channel="hex" />
        <ColorPicker.ChannelInput channel="alpha" />
        <ColorPicker.ValueText />
        <ColorPicker.Trigger>
          <ColorPicker.TransparencyGrid />
          <ColorPicker.ValueSwatch />
        </ColorPicker.Trigger>
      </ColorPicker.Control>
      <ColorPicker.Positioner>
        <ColorPicker.Content />
      </ColorPicker.Positioner>
      <ColorPicker.HiddenInput />
    </ColorPicker.Root>
    <Field.HelperText>Additional Info</Field.HelperText>
    <Field.ErrorText>Error Info</Field.ErrorText>
  </Field.Root>
)

API Reference

Root

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
closeOnSelectfalse
boolean

Whether to close the color picker when a swatch is selected

defaultOpen
boolean

The initial open state of the color picker when it is first rendered. Use when you do not need to control its open state.

defaultValue
Color

The initial value of the color picker when it is first rendered. Use when you do not need to control the state of the color picker.

disabled
boolean

Whether the color picker is disabled

format'rgba'
ColorFormat

The 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; channelSliderT...

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.

lazyMountfalse
boolean

Whether to enable lazy mounting

name
string

The name for the form input

onExitComplete
() => void

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

Whether the color picker is open

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

unmountOnExitfalse
boolean

Whether to unmount on exit.

value#000000
Color

The current color value

Data AttributeValue
[data-scope]color-picker
[data-part]root
[data-disabled]Present when disabled
[data-readonly]Present when read-only

AreaBackground

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Area

PropDefaultType
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

AreaThumb

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]color-picker
[data-part]area-thumb
[data-disabled]Present when disabled

ChannelInput

PropDefaultType
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

Data AttributeValue
[data-scope]color-picker
[data-part]channel-input
[data-channel]The color channel of the channelinput
[data-disabled]Present when disabled

ChannelSliderLabel

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]color-picker
[data-part]channel-slider-label
[data-channel]The color channel of the channelsliderlabel

ChannelSlider

PropDefaultType
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

Data AttributeValue
[data-scope]color-picker
[data-part]channel-slider
[data-channel]The color channel of the channelslider
[data-orientation]The orientation of the channelslider

ChannelSliderThumb

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[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

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[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

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]color-picker
[data-part]channel-slider-value-text
[data-channel]The color channel of the channelslidervaluetext

Content

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]color-picker
[data-part]content
[data-placement]The placement of the content
[data-state]"open" | "closed"

Control

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]color-picker
[data-part]control
[data-disabled]Present when disabled
[data-readonly]Present when read-only
[data-state]"open" | "closed"
[data-focus]Present when focused

EyeDropperTrigger

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]color-picker
[data-part]eye-dropper-trigger
[data-disabled]Present when disabled

FormatSelect

PropDefaultType
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

PropDefaultType
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

PropDefaultType
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

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]color-picker
[data-part]label
[data-disabled]Present when disabled
[data-readonly]Present when read-only
[data-focus]Present when focused

Positioner

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

RootProvider

PropDefaultType
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

lazyMountfalse
boolean

Whether to enable lazy mounting

onExitComplete
() => void

Function called when the animation ends in the closed state

present
boolean

Whether the node is present (controlled by the user)

unmountOnExitfalse
boolean

Whether to unmount on exit.

SwatchGroup

PropDefaultType
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

PropDefaultType
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

PropDefaultType
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

Data AttributeValue
[data-scope]color-picker
[data-part]swatch
[data-state]"checked" | "unchecked"
[data-value]

SwatchTrigger

PropDefaultType
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

Data AttributeValue
[data-scope]color-picker
[data-part]swatch-trigger
[data-state]"checked" | "unchecked"
[data-value]
[data-disabled]Present when disabled

TransparencyGrid

PropDefaultType
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

Trigger

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]color-picker
[data-part]trigger
[data-disabled]Present when disabled
[data-readonly]Present when read-only
[data-placement]The placement of the trigger
[data-state]"open" | "closed"
[data-focus]Present when focused

ValueSwatch

PropDefaultType
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

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]color-picker
[data-part]value-text
[data-disabled]Present when disabled
[data-focus]Present when focused

View

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

Accessibility

Keyboard Support

KeyDescription
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