Color Picker Primitive

View Markdown

Color Picker coordinates color parsing, two-dimensional area input, channel controls, editable values, presets, and native form submission.

Usage Guidelines

Compose only the controls your picker needs. Area, channel, text-entry, format, swatch, clear, and EyeDropper parts share one Root state model and can be arranged for the product workflow.
Use HiddenInput for native forms. It is the sole submitting control and carries the accepted canonical color string, name, form association, and required state.
Choose one format-control path. Use FormatSelect for native progressive enhancement or place one Select Root inside FormatControl for a composite popup. Both edit the same hex, rgb, hsl, or hsb format state.
Start with the styled Color Picker for product UI. The related styled component composes Popover, Select, and Native Select around this Primitive contract; use the Primitive parts when you need custom anatomy.

Anatomy

Use the Astro primitive adapter to render Color Picker anatomy with the Runtime wiring included.

---
import { ColorPicker } from "@starwind-ui/astro/color-picker";
---

<ColorPicker.Root>
  <ColorPicker.Label>Color</ColorPicker.Label>
  <ColorPicker.Control>
    <ColorPicker.ValueSwatch />
    <ColorPicker.ValueInput />
    <ColorPicker.ValueText />
  </ColorPicker.Control>
  <ColorPicker.Area xChannel="saturation" yChannel="brightness">
    <ColorPicker.AreaBackground />
    <ColorPicker.AreaThumb />
    <ColorPicker.AreaInput axis="x" />
    <ColorPicker.AreaInput axis="y" />
  </ColorPicker.Area>
  <ColorPicker.ChannelSlider channel="hue">
    <ColorPicker.ChannelSliderTrack />
    <ColorPicker.ChannelSliderThumb />
    <ColorPicker.ChannelSliderInput />
  </ColorPicker.ChannelSlider>
  <ColorPicker.ChannelInput channel="hue" />
  <ColorPicker.FormatSelect />
  <ColorPicker.FormatControl />
  <ColorPicker.TransparencyGrid />
  <ColorPicker.SwatchGroup>
    <ColorPicker.Swatch swatchValue="#3b82f6" />
  </ColorPicker.SwatchGroup>
  <ColorPicker.EyeDropperTrigger>Pick from screen</ColorPicker.EyeDropperTrigger>
  <ColorPicker.Clear>Clear</ColorPicker.Clear>
  <ColorPicker.HiddenInput />
</ColorPicker.Root>

Use the React primitive adapter when Color Picker state participates in React rendering.

import { ColorPicker } from "@starwind-ui/react/color-picker";

export function Example() {
  return (
    <ColorPicker.Root>
      <ColorPicker.Label>Color</ColorPicker.Label>
      <ColorPicker.Control>
        <ColorPicker.ValueSwatch />
        <ColorPicker.ValueInput />
        <ColorPicker.ValueText />
      </ColorPicker.Control>
      <ColorPicker.Area xChannel="saturation" yChannel="brightness">
        <ColorPicker.AreaBackground />
        <ColorPicker.AreaThumb />
        <ColorPicker.AreaInput axis="x" />
        <ColorPicker.AreaInput axis="y" />
      </ColorPicker.Area>
      <ColorPicker.ChannelSlider channel="hue">
        <ColorPicker.ChannelSliderTrack />
        <ColorPicker.ChannelSliderThumb />
        <ColorPicker.ChannelSliderInput />
      </ColorPicker.ChannelSlider>
      <ColorPicker.ChannelInput channel="hue" />
      <ColorPicker.FormatSelect />
      <ColorPicker.FormatControl />
      <ColorPicker.TransparencyGrid />
      <ColorPicker.SwatchGroup>
        <ColorPicker.Swatch swatchValue="#3b82f6" />
      </ColorPicker.SwatchGroup>
      <ColorPicker.EyeDropperTrigger>Pick from screen</ColorPicker.EyeDropperTrigger>
      <ColorPicker.Clear>Clear</ColorPicker.Clear>
      <ColorPicker.HiddenInput />
    </ColorPicker.Root>
  );
}

Render the Color Picker data-sw-* contract yourself, then initialize createColorPicker.

<div data-sw-color-picker role="group">
  <span data-sw-color-picker-label>Color</span>
  <div data-sw-color-picker-control>
    <span data-sw-color-picker-value-swatch></span>
    <input data-sw-color-picker-value-input />
    <span data-sw-color-picker-value-text></span>
  </div>
  <div data-sw-color-picker-area data-x-channel="saturation" data-y-channel="brightness">
    <div data-sw-color-picker-area-background></div>
    <span data-sw-color-picker-area-thumb></span>
    <input data-sw-color-picker-area-input type="range" data-axis="x" />
    <input data-sw-color-picker-area-input type="range" data-axis="y" />
  </div>
  <div data-sw-color-picker-channel-slider data-channel="hue">
    <div data-sw-color-picker-channel-slider-track></div>
    <span data-sw-color-picker-channel-slider-thumb></span>
    <input data-sw-color-picker-channel-input type="range" />
  </div>
  <input data-sw-color-picker-channel-field data-channel="hue" />
  <select data-sw-color-picker-format-select></select>
  <div data-sw-color-picker-format-control></div>
  <span data-sw-color-picker-transparency-grid></span>
  <div data-sw-color-picker-swatch-group role="group">
    <button data-sw-color-picker-swatch type="button" data-value="#3b82f6"></button>
  </div>
  <button data-sw-color-picker-eye-dropper type="button" hidden>Pick from screen</button>
  <button data-sw-color-picker-clear type="button">Clear</button>
  <input data-sw-color-picker-hidden-input type="text" aria-hidden="true" tabindex="-1" />
</div>

<script type="module">
  import { createColorPicker } from "@starwind-ui/runtime/color-picker";

  const root = document.querySelector("[data-sw-color-picker]");
  if (root) {
    createColorPicker(root);
  }
</script>

Format Controls

FormatSelect is a native <select> and remains useful before JavaScript initializes. FormatControl is the discovery wrapper for one composite Select Root; Select continues to own popup, focus, keyboard, and item behavior. Do not render both paths for the same user-facing control.

Composite Format Control

Compose FormatControl around one Runtime-backed Select. Color Picker owns the accepted format and synchronizes Select without creating another form value.

---
import { ColorPicker } from "@starwind-ui/astro/color-picker";
import { Select } from "@starwind-ui/astro/select";
---

<ColorPicker.Root defaultValue="#3b82f6" format="hex" name="accent">
  <ColorPicker.ValueInput />
  <ColorPicker.FormatControl>
    <Select.Root defaultValue="hex">
      <Select.Trigger aria-label="Color format">
        <Select.Value>HEX</Select.Value>
      </Select.Trigger>
      <Select.Positioner>
        <Select.Popup>
          <Select.List>
            <Select.Item value="hex"><Select.ItemText>HEX</Select.ItemText></Select.Item>
            <Select.Item value="rgb"><Select.ItemText>RGB</Select.ItemText></Select.Item>
            <Select.Item value="hsl"><Select.ItemText>HSL</Select.ItemText></Select.Item>
            <Select.Item value="hsb"><Select.ItemText>HSB</Select.ItemText></Select.Item>
          </Select.List>
        </Select.Popup>
      </Select.Positioner>
    </Select.Root>
  </ColorPicker.FormatControl>
  <ColorPicker.HiddenInput />
</ColorPicker.Root>

import { ColorPicker } from "@starwind-ui/react/color-picker";
import { Select } from "@starwind-ui/react/select";

export function CompositeFormatControl() {
  return (
    <ColorPicker.Root defaultValue="#3b82f6" format="hex" name="accent">
      <ColorPicker.ValueInput />
      <ColorPicker.FormatControl>
        <Select.Root defaultValue="hex">
          <Select.Trigger aria-label="Color format">
            <Select.Value>HEX</Select.Value>
          </Select.Trigger>
          <Select.Positioner>
            <Select.Popup>
              <Select.List>
                <Select.Item value="hex"><Select.ItemText>HEX</Select.ItemText></Select.Item>
                <Select.Item value="rgb"><Select.ItemText>RGB</Select.ItemText></Select.Item>
                <Select.Item value="hsl"><Select.ItemText>HSL</Select.ItemText></Select.Item>
                <Select.Item value="hsb"><Select.ItemText>HSB</Select.ItemText></Select.Item>
              </Select.List>
            </Select.Popup>
          </Select.Positioner>
        </Select.Root>
      </ColorPicker.FormatControl>
      <ColorPicker.HiddenInput />
    </ColorPicker.Root>
  );
}

<div data-sw-color-picker role="group">
  <input data-sw-color-picker-value-input value="#3b82f6" />
  <div data-sw-color-picker-format-control>
    <div data-sw-select data-default-value="hex">
      <button data-sw-select-trigger type="button" aria-label="Color format">
        <span data-sw-select-value>HEX</span>
      </button>
      <div data-sw-select-positioner>
        <div data-sw-select-popup hidden>
          <div data-sw-select-list>
            <div data-sw-select-item data-value="hex"><span data-sw-select-item-text>HEX</span></div>
            <div data-sw-select-item data-value="rgb"><span data-sw-select-item-text>RGB</span></div>
            <div data-sw-select-item data-value="hsl"><span data-sw-select-item-text>HSL</span></div>
            <div data-sw-select-item data-value="hsb"><span data-sw-select-item-text>HSB</span></div>
          </div>
        </div>
      </div>
      <input data-sw-select-input type="hidden" />
    </div>
  </div>
  <input data-sw-color-picker-hidden-input type="text" name="accent" aria-hidden="true" tabindex="-1" />
</div>

<script type="module">
  import { createColorPicker } from "@starwind-ui/runtime/color-picker";
  import { createSelect } from "@starwind-ui/runtime/select";

  const root = document.querySelector("[data-sw-color-picker]");
  const selectRoot = root?.querySelector("[data-sw-select]");
  if (root && selectRoot) {
    createSelect(selectRoot);
    createColorPicker(root, {
      defaultValue: "#3b82f6",
      format: "hex",
      name: "accent",
    });
  }
</script>

Use the native path when browser-native interaction and progressive enhancement are the priority.

Native Format Select

Use FormatSelect for a progressively enhanced native select with the same hex, rgb, hsl, and hsb format state.

---
import { ColorPicker } from "@starwind-ui/astro/color-picker";
---

<ColorPicker.Root defaultValue="#3b82f6" format="hex" name="accent">
  <ColorPicker.ValueInput />
  <ColorPicker.FormatSelect aria-label="Color format">
    <option value="hex">HEX</option>
    <option value="rgb">RGB</option>
    <option value="hsl">HSL</option>
    <option value="hsb">HSB</option>
  </ColorPicker.FormatSelect>
  <ColorPicker.HiddenInput />
</ColorPicker.Root>

import { ColorPicker } from "@starwind-ui/react/color-picker";

export function NativeFormatSelect() {
  return (
    <ColorPicker.Root defaultValue="#3b82f6" format="hex" name="accent">
      <ColorPicker.ValueInput />
      <ColorPicker.FormatSelect aria-label="Color format">
        <option value="hex">HEX</option>
        <option value="rgb">RGB</option>
        <option value="hsl">HSL</option>
        <option value="hsb">HSB</option>
      </ColorPicker.FormatSelect>
      <ColorPicker.HiddenInput />
    </ColorPicker.Root>
  );
}

<div data-sw-color-picker role="group">
  <input data-sw-color-picker-value-input value="#3b82f6" />
  <select data-sw-color-picker-format-select aria-label="Color format">
    <option value="hex">HEX</option>
    <option value="rgb">RGB</option>
    <option value="hsl">HSL</option>
    <option value="hsb">HSB</option>
  </select>
  <input data-sw-color-picker-hidden-input type="text" name="accent" aria-hidden="true" tabindex="-1" />
</div>

<script type="module">
  import { createColorPicker } from "@starwind-ui/runtime/color-picker";

  const root = document.querySelector("[data-sw-color-picker]");
  if (root) {
    createColorPicker(root, {
      defaultValue: "#3b82f6",
      format: "hex",
      name: "accent",
    });
  }
</script>

State, Events, and Commands

The value and format state models are reflected across every owned part. Listen for cancellable starwind:value-change, committed starwind:value-committed, and post-commit starwind:format-change events on Root. Use the controller setters for application state; setValue and setFormat accept { emit: false } for silent synchronization. For a composite control, Color Picker internally sends starwind:set-value, starwind:set-disabled, and starwind:set-readonly commands to the nested Select. A canceled Select value change is ignored, and its nested value event does not escape as a Color Picker value event.

Forms and Reset

HiddenInput is the sole submitted color field. Keep name, form, and required on Color Picker Root rather than either format control; Runtime removes form ownership from the composite Select. Native form reset restores the initial value and format, clears drafts, and silently reconciles both native and composite controls.

Styling Color Thumbs

Runtime writes --sw-color-picker-area-thumb-color on AreaThumb and --sw-color-picker-channel-thumb-color on ChannelSliderThumb. The area value is opaque, ordinary channel thumbs use the accepted color, alpha preserves transparency, and empty values clear both variables. Paint an inner layer from these variables so the thumb remains visible at track boundaries without changing its position or interaction geometry.

Accessibility

Area and channel controls expose native range inputs for keyboard operation. Swatches are native buttons with selected state reflected through aria-pressed. Give FormatSelect an accessible label; for FormatControl, label the nested Select Trigger and let Select own combobox and listbox semantics. Supply localized value and color descriptions with getAriaValueText, getAreaRoleDescription, and getColorDescription when the defaults do not fit your interface.

API Reference

Root

Owns the Color Picker Runtime controller and shared value, format, interaction, locale, and form options.

Default element: div
Discovery hook: data-sw-color-picker
Role: group

Props

Prop Type Default

value ColorPickerValue -

Description: Controls the accepted color value.
Kind: control
Targets: -
Full type: ColorPickerValue

defaultValue ColorPickerValue "#000000"

Description: Sets the initial uncontrolled color value.
Kind: control
Targets: -
Full type: ColorPickerValue

format ColorPickerFormat "hex"

Description: Controls the color string format.
Kind: control
Targets: -
Full type: ColorPickerFormat

alpha boolean true

Description: Enables alpha-channel editing.
Kind: option
Targets: -
Full type: boolean

allowEmpty boolean false

Description: Allows the accepted value to be null.
Kind: option
Targets: -
Full type: boolean

disabled boolean false

Description: Disables every interactive picker part.
Kind: option
Targets: -
Full type: boolean

readOnly boolean false

Description: Prevents edits while preserving focus and value inspection.
Kind: option
Targets: -
Full type: boolean

name string -

Description: Sets the submitted form field name.
Kind: option
Targets: -
Full type: string

form string -

Description: Associates the hidden input with an external form.
Kind: option
Targets: -
Full type: string

required boolean false

Description: Marks the hidden form input as required.
Kind: option
Targets: -
Full type: boolean

locale string -

Description: Sets the locale used for accessible color descriptions.
Kind: option
Targets: -
Full type: string

dir ColorPickerDirection -

Description: Sets left-to-right or right-to-left direction explicitly.
Kind: option
Targets: -
Full type: ColorPickerDirection

getAriaValueText ColorPickerOptions['getAriaValueText'] -

Description: Customizes accessible range value text.
Kind: option
Targets: -
Full type: ColorPickerOptions['getAriaValueText']

getAreaRoleDescription ColorPickerOptions['getAreaRoleDescription'] -

Description: Customizes the color-area role description.
Kind: option
Targets: -
Full type: ColorPickerOptions['getAreaRoleDescription']

getColorDescription ColorPickerOptions['getColorDescription'] -

Description: Customizes the accessible description of a color.
Kind: option
Targets: -
Full type: ColorPickerOptions['getColorDescription']

onValueChange (value: ColorPickerColor | null, details: ColorPickerValueChangeDetails) => void -

Description: Receives cancellable continuous value-change details before commit.
Kind: callback
Targets: -
Full type: (value: ColorPickerColor | null, details: ColorPickerValueChangeDetails) => void

onValueCommitted (value: ColorPickerColor | null, details: ColorPickerValueCommitDetails) => void -

Description: Receives the accepted value when an interaction commits.
Kind: callback
Targets: -
Full type: (value: ColorPickerColor | null, details: ColorPickerValueCommitDetails) => void

onFormatChange (format: ColorPickerFormat, details: ColorPickerFormatChangeDetails) => void -

Description: Receives the accepted format after it changes.
Kind: callback
Targets: -
Full type: (format: ColorPickerFormat, details: ColorPickerFormatChangeDetails) => void

Events

Event Callback Value

valueChange onValueChange value: ColorPickerColor | null

Description: Cancelable continuous change emitted before a proposed value commits.
DOM event: starwind:value-change
Details type: ColorPickerValueChangeDetails
Timing: before-state-commit
Cancelable: Yes

valueCommitted onValueCommitted value: ColorPickerColor | null

Description: Emitted after an accepted interaction value commits.
DOM event: starwind:value-committed
Details type: ColorPickerValueCommitDetails
Timing: after-state-commit
Cancelable: No

formatChange onFormatChange format: ColorPickerFormat

Description: Emitted after the accepted string format changes.
DOM event: starwind:format-change
Details type: ColorPickerFormatChangeDetails
Timing: after-state-commit
Cancelable: No

State

State Type Props

value ColorPickerColor | null value / defaultValue

Description: The accepted immutable color value, or null when empty values are allowed.
Initial attribute: data-value
Runtime getter: getValue
Runtime setter: setValue
State control support: React supports controlled and default state with value and defaultValue props. Runtime/HTML reads initial state from data-value, emits starwind:value-change and starwind:value-committed, and updates with setValue. Astro adapters render initial/default state and apply changes through Runtime setter methods after load.

format ColorPickerFormat format

Description: The accepted color string format used by editable and display parts.
Initial attribute: data-format
Runtime getter: getFormat
Runtime setter: setFormat
State control support: React supports controlled state with the format prop. Runtime/HTML reads initial state from data-format, emits starwind:format-change, and updates with setFormat. Astro adapters render initial/default state and apply changes through Runtime setter methods after load.

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker - Marks the Root part so Starwind Runtime can find it.

State

Attribute Value Description

data-value - Reflects the value state on the Root part.

data-format - Reflects the format state on the Root part.

data-invalid - Reflects the invalid state on the Root part.

Metadata

Attribute Value Description

data-alpha - Reflects the alpha prop on the Root part.

data-allow-empty - Reflects the allow empty prop on the Root part.

data-disabled - Reflects the disabled prop on the Root part.

data-readonly - Reflects the readonly prop on the Root part.

data-name - Reflects the name prop on the Root part.

data-form - Reflects the form prop on the Root part.

data-required - Reflects the required prop on the Root part.

data-locale - Reflects the locale prop on the Root part.

Label

Labels the color picker.

Default element: span
Discovery hook: data-sw-color-picker-label
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-label - Marks the Label part so Starwind Runtime can find it.

Control

Groups the visible picker controls.

Default element: div
Discovery hook: data-sw-color-picker-control
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-control - Marks the Control part so Starwind Runtime can find it.

Value Input

Accepts and validates a complete color string draft.

Default element: input
Discovery hook: data-sw-color-picker-value-input
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-value-input - Marks the Value Input part so Starwind Runtime can find it.

State

Attribute Value Description

data-invalid - Reflects the invalid state on the Value Input part.

Value Swatch

Displays the currently accepted color.

Default element: span
Discovery hook: data-sw-color-picker-value-swatch
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-value-swatch - Marks the Value Swatch part so Starwind Runtime can find it.

Value Text

Displays the currently accepted color as text.

Default element: span
Discovery hook: data-sw-color-picker-value-text
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-value-text - Marks the Value Text part so Starwind Runtime can find it.

Area

Coordinates two color channels across horizontal and vertical axes.

Default element: div
Discovery hook: data-sw-color-picker-area
Role: -

Props

Prop Type Default

xChannel ColorPickerChannel -

Description: Selects the channel controlled by the horizontal axis.
Kind: attribute
Targets: area
Full type: ColorPickerChannel

yChannel ColorPickerChannel -

Description: Selects the channel controlled by the vertical axis.
Kind: attribute
Targets: area
Full type: ColorPickerChannel

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-area - Marks the Area part so Starwind Runtime can find it.

State

Attribute Value Description

data-focused - Reflects the focused state on the Area part.

data-dragging - Reflects the dragging state on the Area part.

data-disabled - Reflects the disabled state on the Area part.

data-readonly - Reflects the readonly state on the Area part.

Metadata

Attribute Value Description

data-x-channel - Reflects the x channel prop on the Area part.

data-y-channel - Reflects the y channel prop on the Area part.

Area Background

Paints the two-dimensional color-area background.

Default element: div
Discovery hook: data-sw-color-picker-area-background
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-area-background - Marks the Area Background part so Starwind Runtime can find it.

Area Thumb

Shows the accepted position in the color area.

Default element: span
Discovery hook: data-sw-color-picker-area-thumb
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-area-thumb - Marks the Area Thumb part so Starwind Runtime can find it.

State

Attribute Value Description

data-focused - Reflects the focused state on the Area Thumb part.

data-dragging - Reflects the dragging state on the Area Thumb part.

data-disabled - Reflects the disabled state on the Area Thumb part.

data-readonly - Reflects the readonly state on the Area Thumb part.

Area Input

Provides a native range input for one color-area axis.

Default element: input
Discovery hook: data-sw-color-picker-area-input
Role: -

Props

Prop Type Default

axis "x" | "y" -

Description: Selects the controlled area axis.
Kind: attribute
Targets: areaInput
Full type: "x" | "y"

step number -

Description: Sets the range step.
Kind: attribute
Targets: areaInput, channelSliderInput
Full type: number

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-area-input - Marks the Area Input part so Starwind Runtime can find it.

Metadata

Attribute Value Description

data-axis - Reflects the axis prop on the Area Input part.

data-step - Reflects the step prop on the Area Input part.

Channel Slider

Coordinates one color channel along a horizontal or vertical track.

Default element: div
Discovery hook: data-sw-color-picker-channel-slider
Role: -

Props

Prop Type Default

channel ColorPickerChannel -

Description: Selects the controlled color channel.
Kind: attribute
Targets: channelSlider, channelInput
Full type: ColorPickerChannel

orientation "horizontal" | "vertical" "horizontal"

Description: Sets the slider orientation.
Kind: attribute
Targets: channelSlider
Full type: "horizontal" | "vertical"

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-channel-slider - Marks the Channel Slider part so Starwind Runtime can find it.

State

Attribute Value Description

data-focused - Reflects the focused state on the Channel Slider part.

data-dragging - Reflects the dragging state on the Channel Slider part.

data-disabled - Reflects the disabled state on the Channel Slider part.

data-readonly - Reflects the readonly state on the Channel Slider part.

Metadata

Attribute Value Description

data-channel - Reflects the channel prop on the Channel Slider part.

data-orientation - Reflects the orientation prop on the Channel Slider part.

Channel Slider Track

Paints the selected channel's range.

Default element: div
Discovery hook: data-sw-color-picker-channel-slider-track
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-channel-slider-track - Marks the Channel Slider Track part so Starwind Runtime can find it.

Channel Slider Thumb

Shows the accepted channel position.

Default element: span
Discovery hook: data-sw-color-picker-channel-slider-thumb
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-channel-slider-thumb - Marks the Channel Slider Thumb part so Starwind Runtime can find it.

State

Attribute Value Description

data-focused - Reflects the focused state on the Channel Slider Thumb part.

data-dragging - Reflects the dragging state on the Channel Slider Thumb part.

data-disabled - Reflects the disabled state on the Channel Slider Thumb part.

data-readonly - Reflects the readonly state on the Channel Slider Thumb part.

Channel Slider Input

Provides the native range input for a channel slider.

Default element: input
Discovery hook: data-sw-color-picker-channel-input
Role: -

Props

Prop Type Default

step number -

Description: Sets the range step.
Kind: attribute
Targets: areaInput, channelSliderInput
Full type: number

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-channel-input - Marks the Channel Slider Input part so Starwind Runtime can find it.

Metadata

Attribute Value Description

data-step - Reflects the step prop on the Channel Slider Input part.

Channel Input

Accepts and validates a numeric channel draft.

Default element: input
Discovery hook: data-sw-color-picker-channel-field
Role: -

Props

Prop Type Default

channel ColorPickerChannel -

Description: Selects the edited color channel.
Kind: attribute
Targets: channelSlider, channelInput
Full type: ColorPickerChannel

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-channel-field - Marks the Channel Input part so Starwind Runtime can find it.

State

Attribute Value Description

data-invalid - Reflects the invalid state on the Channel Input part.

Metadata

Attribute Value Description

data-channel - Reflects the channel prop on the Channel Input part.

Format Select

The progressively enhanced native select for hex, rgb, hsl, and hsb editing formats.

Default element: select
Discovery hook: data-sw-color-picker-format-select
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-format-select - Runtime discovery hook for the native format control.

Format Control

Wraps one Runtime-backed Select Root as the composite format control without reimplementing Select behavior.

Default element: div
Discovery hook: data-sw-color-picker-format-control
Role: -

State

State Type Props

format ColorPickerFormat format

Description: The accepted color string format used by editable and display parts.
Initial attribute: data-format
Runtime getter: getFormat
Runtime setter: setFormat
State control support: React supports controlled state with the format prop. Runtime/HTML reads initial state from data-format, emits starwind:format-change, and updates with setFormat. Astro adapters render initial/default state and apply changes through Runtime setter methods after load.

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-format-control - Runtime discovery hook for the composite format-control wrapper.

State

Attribute Value Description

data-format - The accepted hex, rgb, hsl, or hsb editing format.

data-disabled - Present when Color Picker disables the composite Select.

data-readonly - Present when Color Picker makes the composite Select read-only.

Transparency Grid

Provides a checkerboard surface beneath translucent colors.

Default element: span
Discovery hook: data-sw-color-picker-transparency-grid
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-transparency-grid - Marks the Transparency Grid part so Starwind Runtime can find it.

Swatch Group

Groups preset color swatches.

Default element: div
Discovery hook: data-sw-color-picker-swatch-group
Role: group

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-swatch-group - Marks the Swatch Group part so Starwind Runtime can find it.

Swatch

Selects a preset color with native button semantics.

Default element: button
Discovery hook: data-sw-color-picker-swatch
Role: -

Props

Prop Type Default

swatchValue ColorPickerValue -

Description: Sets the preset color.
Kind: attribute
Targets: swatch
Full type: ColorPickerValue

swatchDisabled boolean -

Description: Disables this swatch.
Kind: attribute
Targets: swatch
Full type: boolean

State

State Type Props

value ColorPickerColor | null value / defaultValue

Description: The accepted immutable color value, or null when empty values are allowed.
Initial attribute: data-value
Runtime getter: getValue
Runtime setter: setValue
State control support: React supports controlled and default state with value and defaultValue props. Runtime/HTML reads initial state from data-value, emits starwind:value-change and starwind:value-committed, and updates with setValue. Astro adapters render initial/default state and apply changes through Runtime setter methods after load.

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-swatch - Marks the Swatch part so Starwind Runtime can find it.

State

Attribute Value Description

data-selected - Reflects the selected state on the Swatch part.

Metadata

Attribute Value Description

data-value - Reflects the value prop on the Swatch part.

data-disabled - Reflects the disabled prop on the Swatch part.

Eye Dropper Trigger

Opens the platform EyeDropper when that capability is available.

Default element: button
Discovery hook: data-sw-color-picker-eye-dropper
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-eye-dropper - Marks the Eye Dropper Trigger part so Starwind Runtime can find it.

data-unsupported - Marks the Eye Dropper Trigger part so Starwind Runtime can find it.

Clear

Clears the value when empty values are allowed.

Default element: button
Discovery hook: data-sw-color-picker-clear
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-clear - Marks the Clear part so Starwind Runtime can find it.

Hidden Input

The sole hidden native input used for form submission.

Default element: input
Discovery hook: data-sw-color-picker-hidden-input
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-color-picker-hidden-input - Marks the Hidden Input part so Starwind Runtime can find it.

Runtime API

Factory: createColorPicker
Import: @starwind-ui/runtime/color-picker
Root hook: root data-sw-color-picker
Option props: value, defaultValue, format, alpha, allowEmpty, disabled, readOnly, name, form, required, locale, dir, getAriaValueText, getAreaRoleDescription, getColorDescription, onValueChange, onValueCommitted, onFormatChange

Option Lifecycles

Option	Lifecycle
value	setter-backed
defaultValue	constructor-only
format	setter-backed
alpha	setter-backed
allowEmpty	setter-backed
disabled	setter-backed
readOnly	setter-backed
name	setter-backed
form	setter-backed
required	setter-backed
locale	setter-backed
dir	setter-backed
getAriaValueText	setter-backed
getAreaRoleDescription	setter-backed
getColorDescription	setter-backed
onValueChange	constructor-only
onValueCommitted	constructor-only
onFormatChange	constructor-only

Runtime Setters

Method Target Description

setValue state: value Synchronizes the accepted value and can suppress event emission.

setFormat state: format Synchronizes the accepted format and can suppress event emission.

setDisabled prop: disabled Updates disabled state across every interactive part.

setReadOnly prop: readOnly Updates readonly state across editable parts.

setName prop: name Updates the hidden input's form field name.

setOptions props: alpha, allowEmpty, dir, form, getAreaRoleDescription, getAriaValueText, getColorDescription, locale, required Refreshes mutable locale, direction, accessibility, alpha, empty, and form options.

Form Participation

Fact	Value
Form props	form, name, required, value
Hidden input	hiddenInput (text)
Field integration	Yes

CSS Variables

Variable	Parts	Source	Description
`--sw-color-picker-color`	`root`	runtime	Canonical accepted color serialized for CSS painting.
`--sw-color-picker-hue`	`root`	runtime	Accepted HSB hue as a unitless number.
`--sw-color-picker-saturation`	`root`	runtime	Accepted HSB saturation percentage.
`--sw-color-picker-brightness`	`root`	runtime	Accepted HSB brightness percentage.
`--sw-color-picker-alpha`	`root`	runtime	Accepted alpha as a unitless zero-to-one number.
`--sw-color-picker-area-x`	`areaThumb`	runtime	Horizontal area thumb position.
`--sw-color-picker-area-y`	`areaThumb`	runtime	Vertical area thumb position.
`--sw-color-picker-area-thumb-color`	`areaThumb`	runtime	Resolved display color painted by the color-area thumb.
`--sw-color-picker-channel-position`	`channelSlider`	runtime	Channel slider thumb position.
`--sw-color-picker-channel-thumb-color`	`channelSliderThumb`	runtime	Resolved display color painted by a channel slider thumb.
`--sw-color-picker-swatch-color`	`swatch`	runtime	Resolved swatch color.
`--sw-color-picker-area-background`	`areaBackground`	styled-adapter	Base color-area background layer.
`--sw-color-picker-area-background-overlay`	`areaBackground`	styled-adapter	Color-area saturation/brightness overlay layer.
`--sw-color-picker-channel-gradient`	`channelSliderTrack`	styled-adapter	Gradient painted behind a channel slider.
`--sw-color-picker-transparency-grid-size`	`transparencyGrid`	styled-adapter	Checkerboard tile size used beneath translucent colors.

Component Relationship

Color Picker Direct primitive

Layer Metadata

Color Picker Primitive uses createColorPicker. Styled components: Color Picker.

primitive Color Picker Primitive Color Picker Primitive uses createColorPicker. Styled components: Color Picker. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters color-picker Color Picker Form Value Control Controls that participate directly in form value submission. /docs/primitives/color-picker/ createColorPicker @starwind-ui/runtime/color-picker /docs/runtime/#create-color-picker root value defaultValue format alpha allowEmpty disabled readOnly name form required locale dir getAriaValueText getAreaRoleDescription getColorDescription onValueChange onValueCommitted onFormatChange raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the Color Picker data-sw-* contract yourself, then initialize createColorPicker. html Use the Astro primitive adapter to render Color Picker anatomy with the Runtime wiring included. Use the React primitive adapter when Color Picker state participates in React rendering. tsx div data-sw-color-picker group ColorPickerValue Controls the accepted color value. Sets the initial uncontrolled color value. ColorPickerFormat Controls the color string format. boolean Enables alpha-channel editing. Allows the accepted value to be null. Disables every interactive picker part. Prevents edits while preserving focus and value inspection. string Sets the submitted form field name. Associates the hidden input with an external form. Marks the hidden form input as required. Sets the locale used for accessible color descriptions. ColorPickerDirection Sets left-to-right or right-to-left direction explicitly. ColorPickerOptions['getAriaValueText'] Customizes accessible range value text. ColorPickerOptions['getAreaRoleDescription'] Customizes the color-area role description. ColorPickerOptions['getColorDescription'] Customizes the accessible description of a color. (value: ColorPickerColor | null, details: ColorPickerValueChangeDetails) => void ColorPickerValueChangeDetails Receives cancellable continuous value-change details before commit. (value: ColorPickerColor | null, details: ColorPickerValueCommitDetails) => void ColorPickerValueCommitDetails Receives the accepted value when an interaction commits. (format: ColorPickerFormat, details: ColorPickerFormatChangeDetails) => void ColorPickerFormatChangeDetails Receives the accepted format after it changes. runtime Marks the Root part so Starwind Runtime can find it. data-value state Reflects the value state on the Root part. data-format Reflects the format state on the Root part. data-alpha prop Reflects the alpha prop on the Root part. data-allow-empty Reflects the allow empty prop on the Root part. data-disabled Reflects the disabled prop on the Root part. data-readonly Reflects the readonly prop on the Root part. data-invalid Reflects the invalid state on the Root part. data-name Reflects the name prop on the Root part. data-form Reflects the form prop on the Root part. data-required Reflects the required prop on the Root part. data-locale Reflects the locale prop on the Root part. ColorPickerColor | null getValue setValue getFormat setFormat valueChange starwind:value-change valueCommitted starwind:value-committed formatChange starwind:format-change setDisabled setReadOnly setName setOptions alpha, allowEmpty, dir, form, getAreaRoleDescription, getAriaValueText, getColorDescription, locale, required label span data-sw-color-picker-label Marks the Label part so Starwind Runtime can find it. control data-sw-color-picker-control Marks the Control part so Starwind Runtime can find it. valueInput input data-sw-color-picker-value-input Marks the Value Input part so Starwind Runtime can find it. Reflects the invalid state on the Value Input part. valueSwatch data-sw-color-picker-value-swatch Marks the Value Swatch part so Starwind Runtime can find it. valueText data-sw-color-picker-value-text Marks the Value Text part so Starwind Runtime can find it. area data-sw-color-picker-area xChannel ColorPickerChannel Selects the channel controlled by the horizontal axis. yChannel Selects the channel controlled by the vertical axis. Marks the Area part so Starwind Runtime can find it. data-x-channel Reflects the x channel prop on the Area part. data-y-channel Reflects the y channel prop on the Area part. data-focused Reflects the focused state on the Area part. data-dragging Reflects the dragging state on the Area part. Reflects the disabled state on the Area part. Reflects the readonly state on the Area part. areaBackground data-sw-color-picker-area-background Marks the Area Background part so Starwind Runtime can find it. areaThumb data-sw-color-picker-area-thumb Marks the Area Thumb part so Starwind Runtime can find it. Reflects the focused state on the Area Thumb part. Reflects the dragging state on the Area Thumb part. Reflects the disabled state on the Area Thumb part. Reflects the readonly state on the Area Thumb part. areaInput data-sw-color-picker-area-input axis "x" | "y" Selects the controlled area axis. step number Sets the range step. Marks the Area Input part so Starwind Runtime can find it. data-axis Reflects the axis prop on the Area Input part. data-step Reflects the step prop on the Area Input part. channelSlider data-sw-color-picker-channel-slider channel Selects the controlled color channel. orientation "horizontal" | "vertical" Sets the slider orientation. Marks the Channel Slider part so Starwind Runtime can find it. data-channel Reflects the channel prop on the Channel Slider part. data-orientation Reflects the orientation prop on the Channel Slider part. Reflects the focused state on the Channel Slider part. Reflects the dragging state on the Channel Slider part. Reflects the disabled state on the Channel Slider part. Reflects the readonly state on the Channel Slider part. channelSliderTrack data-sw-color-picker-channel-slider-track Marks the Channel Slider Track part so Starwind Runtime can find it. channelSliderThumb data-sw-color-picker-channel-slider-thumb Marks the Channel Slider Thumb part so Starwind Runtime can find it. Reflects the focused state on the Channel Slider Thumb part. Reflects the dragging state on the Channel Slider Thumb part. Reflects the disabled state on the Channel Slider Thumb part. Reflects the readonly state on the Channel Slider Thumb part. channelSliderInput data-sw-color-picker-channel-input Marks the Channel Slider Input part so Starwind Runtime can find it. Reflects the step prop on the Channel Slider Input part. channelInput data-sw-color-picker-channel-field Selects the edited color channel. Marks the Channel Input part so Starwind Runtime can find it. Reflects the channel prop on the Channel Input part. Reflects the invalid state on the Channel Input part. formatSelect select data-sw-color-picker-format-select Runtime discovery hook for the native format control. formatControl data-sw-color-picker-format-control Runtime discovery hook for the composite format-control wrapper. The accepted hex, rgb, hsl, or hsb editing format. Present when Color Picker disables the composite Select. Present when Color Picker makes the composite Select read-only. transparencyGrid data-sw-color-picker-transparency-grid Marks the Transparency Grid part so Starwind Runtime can find it. swatchGroup data-sw-color-picker-swatch-group Marks the Swatch Group part so Starwind Runtime can find it. swatch button data-sw-color-picker-swatch swatchValue Sets the preset color. swatchDisabled Disables this swatch. Marks the Swatch part so Starwind Runtime can find it. Reflects the value prop on the Swatch part. Reflects the disabled prop on the Swatch part. data-selected Reflects the selected state on the Swatch part. eyeDropperTrigger data-sw-color-picker-eye-dropper Marks the Eye Dropper Trigger part so Starwind Runtime can find it. data-unsupported clear data-sw-color-picker-clear Marks the Clear part so Starwind Runtime can find it. hiddenInput data-sw-color-picker-hidden-input Marks the Hidden Input part so Starwind Runtime can find it. Root role Label Control Value Input aria-invalid Value Swatch Value Text Area Area Background Area Thumb Area Input type aria-roledescription aria-valuetext aria-description Channel Slider Channel Slider Track Channel Slider Thumb Channel Slider Input Channel Input Format Select aria-readonly Format Control Transparency Grid Swatch Group Swatch aria-pressed Eye Dropper Trigger hidden Clear Hidden Input aria-hidden tabIndex @starwind-ui/astro @starwind-ui/astro/color-picker Render uncontrolled initial state and repeatable area/channel/swatch parts; Runtime owns color math, drafts, pointer/keyboard interaction, form synchronization, and EyeDropper capability detection. Use Root's render projection when non-default initial state must be reflected coherently across descendant area, channel, swatch, and hidden-input parts before hydration. @starwind-ui/react @starwind-ui/react/color-picker Bridge value and format through their imperative setters after structural refresh; keep callbacks current without recreating the Runtime controller. Value and format can be controlled; adapters synchronize them through non-emitting Runtime setters while preserving cancellable Runtime change details. /docs/components/color-picker/ Direct primitive direct-primitive Styled component Color Picker