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

<script setup lang="ts">
import { ColorPicker } from '@ark-ui/vue'
</script>

<template>
  <ColorPicker.Root defaultValue="#ff00ff">
    <ColorPicker.Label>Color</ColorPicker.Label>
    <ColorPicker.Control>
      <ColorPicker.ChannelInput channel="hex" />
      <ColorPicker.ChannelInput channel="alpha" />
      <ColorPicker.ValueText />
      <ColorPicker.Trigger>
        <ColorPicker.TransparencyGrid />
        <ColorPicker.Context v-slot="api">
          <ColorPicker.Swatch :value="api.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>
</template>

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:

<script setup lang="ts">
import { ref } from 'vue'
import { ColorPicker } from '@ark-ui/vue'

const value = ref('hsl(20, 100%, 50%)')
</script>

<template>
  <ColorPicker.Root format="hsla" v-model="value">
    <ColorPicker.Label>Color</ColorPicker.Label>
    <ColorPicker.Control>
      <ColorPicker.ChannelInput channel="hex" />
      <ColorPicker.ChannelInput channel="alpha" />
      <ColorPicker.ValueText />
      <ColorPicker.Trigger>
        <ColorPicker.TransparencyGrid />
        <ColorPicker.Context v-slot="api">
          <ColorPicker.Swatch :value="api.value" />
        </ColorPicker.Context>
      </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>
</template>

API Reference

Root

PropDefaultType
asChildfalse
boolean

closeOnSelectfalse
boolean

Whether to close the color picker when a swatch is selected

defaultOpen
boolean

The initial open state of the color picker.

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

modelValue
string

name
string

The name for the form input

open
boolean

Whether the color picker is open

positioning
PositioningOptions

The positioning options for the color picker

readOnly
boolean

Whether the color picker is read-only

unmountOnExitfalse
boolean

Whether to unmount on exit.

EmitEvent
focusOutside
[event: FocusOutsideEvent]

Function called when the focus is moved outside the component

formatChange
[details: FormatChangeDetails]

Function called when the color format changes

interactOutside
[event: InteractOutsideEvent]

Function called when an interaction happens outside the component

openChange
[details: OpenChangeDetails]

Handler that is called when the user opens or closes the color picker.

pointerDownOutside
[event: PointerDownOutsideEvent]

Function called when the pointer is pressed down outside the component

update:modelValue
[value: string]

The callback fired when the model value changes.

update:open
[open: boolean]

valueChange
[details: ValueChangeDetails]

Handler that is called when the value changes, as the user drags.

valueChangeEnd
[details: ValueChangeDetails]

Handler that is called when the user stops dragging.

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

AreaBackground

PropDefaultType
asChildfalse
boolean

Area

PropDefaultType
asChildfalse
boolean

xChannel
ColorChannel

yChannel
ColorChannel

AreaThumb

PropDefaultType
asChildfalse
boolean

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

ChannelInput

PropDefaultType
channel
ExtendedColorChannel

asChildfalse
boolean

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

asChildfalse
boolean

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
asChildfalse
boolean

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
asChildfalse
boolean

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
asChildfalse
boolean

lazyMountfalse
boolean

Whether to enable lazy mounting

present
boolean

Whether the node is present (controlled by the user)

unmountOnExitfalse
boolean

Whether to unmount on exit.

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

Control

PropDefaultType
asChildfalse
boolean

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
asChildfalse
boolean

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

FormatSelect

PropDefaultType
asChildfalse
boolean

FormatTrigger

PropDefaultType
asChildfalse
boolean

HiddenInput

PropDefaultType
asChildfalse
boolean

Label

PropDefaultType
asChildfalse
boolean

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
asChildfalse
boolean

SwatchGroup

PropDefaultType
asChildfalse
boolean

SwatchIndicator

PropDefaultType
asChildfalse
boolean

Swatch

PropDefaultType
value
string | Color

The color value

asChildfalse
boolean

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

asChildfalse
boolean

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
asChildfalse
boolean

size
string

Trigger

PropDefaultType
asChildfalse
boolean

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
asChildfalse
boolean

View

PropDefaultType
format
ColorFormat

asChildfalse
boolean

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