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.

closeOnSelect
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
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 | (() => MaybeElement)

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.

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.

ChannelInput

PropDefaultType
channel
ExtendedColorChannel

asChild
boolean

Render as a different element type.

orientation
Orientation

ChannelSlider

PropDefaultType
channel
ColorChannel

asChild
boolean

Render as a different element type.

orientation
Orientation

ChannelSliderThumb

PropDefaultType
asChild
boolean

Render as a different element type.

ChannelSliderTrack

PropDefaultType
asChild
boolean

Render as a different element type.

Content

PropDefaultType
asChild
boolean

Render as a different element type.

Control

PropDefaultType
asChild
boolean

Render as a different element type.

EyeDropperTrigger

PropDefaultType
asChild
boolean

Render as a different element type.

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.

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

SwatchTrigger

PropDefaultType
value
string | Color

The color value

asChild
boolean

Render as a different element type.

disabled
boolean

Whether the swatch trigger is disabled

TransparencyGrid

PropDefaultType
asChild
boolean

Render as a different element type.

size
string

Trigger

PropDefaultType
asChild
boolean

Render as a different element type.

ValueText

PropDefaultType
asChild
boolean

Render as a different element type.

View

PropDefaultType
format
ColorFormat

asChild
boolean

Render as a different element type.