Ark Logo

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 } from '@ark-ui/react'

export const Basic = () => {
  return (
    <ColorPicker.Root defaultValue="#eb5e41">
      <ColorPicker.Label>Color</ColorPicker.Label>
      <ColorPicker.Control>
        <ColorPicker.ChannelInput channel="hex" />
        <ColorPicker.ChannelInput channel="alpha" />
        <ColorPicker.ValueText />
        <ColorPicker.Trigger>
          <ColorPicker.TransparencyGrid />
          <ColorPicker.Context>
            {(colorPicker) => <ColorPicker.Swatch value={colorPicker.value} />}
          </ColorPicker.Context>
        </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 { useState } from 'react'
import { ColorPicker } from '@ark-ui/react'

export const Controlled = () => {
  const [currentValue, setCurrentValue] = useState('hsl(20, 100%, 50%)')

  return (
    <ColorPicker.Root
      format="hsla"
      value={currentValue}
      onValueChange={(details) => setCurrentValue(details.valueAsString)}
      onValueChangeEnd={(details) => console.log(details.valueAsString)}
    >
      <ColorPicker.Context>
        {(colorPicker) => (
          <>
            <ColorPicker.Label>Color</ColorPicker.Label>
            <ColorPicker.Control>
              <ColorPicker.ChannelInput channel="hex" />
              <ColorPicker.ChannelInput channel="alpha" />
              <ColorPicker.ValueText />
              <ColorPicker.Trigger>
                <ColorPicker.TransparencyGrid />
                <ColorPicker.Swatch value={colorPicker.value} />
              </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.Context>
      <ColorPicker.HiddenInput />
    </ColorPicker.Root>
  )
}

API Reference

Root

PropDefaultType
asChild
boolean

Render as a different element type.

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
string

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 content: string area: string areaGradient: string areaThumb: string channelInput(id: string): string channelSliderTrack(id: ColorChannel): string channelSliderThumb(id: ColorChannel): string }>

The ids of the elements in the color picker. Useful for composition.

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

unmountOnExitfalse
boolean

Whether to unmount on exit.

value
string

The current value of the color picker.

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

AreaBackground

PropDefaultType
asChild
boolean

Render as a different element type.

Area

PropDefaultType
asChild
boolean

Render as a different element type.

xChannel
ColorChannel

yChannel
ColorChannel

AreaThumb

PropDefaultType
asChild
boolean

Render as a different element type.

Data AttributeValue
[data-scope]color-picker
[data-part]area-thumb
[data-disabled]Present when disabled

ChannelInput

PropDefaultType
channel
ExtendedColorChannel

asChild
boolean

Render as a different element type.

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

ChannelSlider

PropDefaultType
channel
ColorChannel

asChild
boolean

Render as a different element type.

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

Render as a different element type.

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

Render as a different element type.

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

Content

PropDefaultType
asChild
boolean

Render as a different element type.

Data AttributeValue
[data-scope]color-picker
[data-part]content
[data-placement]The placement of the content
[data-state]"open" | "closed"

Control

PropDefaultType
asChild
boolean

Render as a different element type.

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

Render as a different element type.

Data AttributeValue
[data-scope]color-picker
[data-part]eye-dropper-trigger
[data-disabled]Present when disabled

FormatSelect

PropDefaultType
asChild
boolean

Render as a different element type.

FormatTrigger

PropDefaultType
asChild
boolean

Render as a different element type.

HiddenInput

PropDefaultType
asChild
boolean

Render as a different element type.

Label

PropDefaultType
asChild
boolean

Render as a different element type.

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

Render as a different element type.

SwatchGroup

PropDefaultType
asChild
boolean

Render as a different element type.

SwatchIndicator

PropDefaultType
asChild
boolean

Render as a different element type.

Swatch

PropDefaultType
value
string | Color

The color value

asChild
boolean

Render as a different element type.

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

Render as a different element type.

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

Render as a different element type.

size
string

Trigger

PropDefaultType
asChild
boolean

Render as a different element type.

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

ValueText

PropDefaultType
asChild
boolean

Render as a different element type.

View

PropDefaultType
format
ColorFormat

asChild
boolean

Render as a different element type.

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