# Color Picker Primitive

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
### Astro
Use the Astro primitive adapter to render Color Picker anatomy with the Runtime wiring included.
```astro
---
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>
```

### React
Use the React primitive adapter when Color Picker state participates in React rendering.
```tsx
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>
  );
}
```

### HTML
Render the Color Picker data-sw-* contract yourself, then initialize createColorPicker.
```html
<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.
#### Astro
```astro
---
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>
```

#### React
```tsx
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>
  );
}
```

#### HTML
```html
<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.
#### Astro
```astro
---
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>
```

#### React
```tsx
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>
  );
}
```

#### HTML
```html
<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.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-color-picker` |
| Role | `group` |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| value | `ColorPickerValue` | - | control | Controls the accepted color value. |
| defaultValue | `ColorPickerValue` | "#000000" | control | Sets the initial uncontrolled color value. |
| format | `ColorPickerFormat` | "hex" | control | Controls the color string format. |
| alpha | `boolean` | true | option | Enables alpha-channel editing. |
| allowEmpty | `boolean` | false | option | Allows the accepted value to be null. |
| disabled | `boolean` | false | option | Disables every interactive picker part. |
| readOnly | `boolean` | false | option | Prevents edits while preserving focus and value inspection. |
| name | `string` | - | option | Sets the submitted form field name. |
| form | `string` | - | option | Associates the hidden input with an external form. |
| required | `boolean` | false | option | Marks the hidden form input as required. |
| locale | `string` | - | option | Sets the locale used for accessible color descriptions. |
| dir | `ColorPickerDirection` | - | option | Sets left-to-right or right-to-left direction explicitly. |
| getAriaValueText | `ColorPickerOptions['getAriaValueText']` | - | option | Customizes accessible range value text. |
| getAreaRoleDescription | `ColorPickerOptions['getAreaRoleDescription']` | - | option | Customizes the color-area role description. |
| getColorDescription | `ColorPickerOptions['getColorDescription']` | - | option | Customizes the accessible description of a color. |
| onValueChange | `(value: ColorPickerColor \| null, details: ColorPickerValueChangeDetails) => void` | - | callback | Receives cancellable continuous value-change details before commit. |
| onValueCommitted | `(value: ColorPickerColor \| null, details: ColorPickerValueCommitDetails) => void` | - | callback | Receives the accepted value when an interaction commits. |
| onFormatChange | `(format: ColorPickerFormat, details: ColorPickerFormatChangeDetails) => void` | - | callback | Receives the accepted format after it changes. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-value` | state | - | Reflects the value state on the Root part. |
| `data-format` | state | - | Reflects the format state on the Root part. |
| `data-alpha` | prop | - | Reflects the alpha prop on the Root part. |
| `data-allow-empty` | prop | - | Reflects the allow empty prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-readonly` | prop | - | Reflects the readonly prop on the Root part. |
| `data-invalid` | state | - | Reflects the invalid state on the Root part. |
| `data-name` | prop | - | Reflects the name prop on the Root part. |
| `data-form` | prop | - | Reflects the form prop on the Root part. |
| `data-required` | prop | - | Reflects the required prop on the Root part. |
| `data-locale` | prop | - | Reflects the locale prop on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| value | `ColorPickerColor \| null` | value | defaultValue | `data-value` | `getValue` | `setValue` | The accepted immutable color value, or null when empty values are allowed. | 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 | - | `data-format` | `getFormat` | `setFormat` | The accepted color string format used by editable and display parts. | 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. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description |
| --- | --- | --- | --- | --- | --- | --- | --- |
| valueChange | onValueChange | starwind:value-change | value: `ColorPickerColor \| null` | ColorPickerValueChangeDetails | before-state-commit | Yes | Cancelable continuous change emitted before a proposed value commits. |
| valueCommitted | onValueCommitted | starwind:value-committed | value: `ColorPickerColor \| null` | ColorPickerValueCommitDetails | after-state-commit | - | Emitted after an accepted interaction value commits. |
| formatChange | onFormatChange | starwind:format-change | format: `ColorPickerFormat` | ColorPickerFormatChangeDetails | after-state-commit | - | Emitted after the accepted string format changes. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setValue` | state: value | emit: false | Yes | Synchronizes the accepted value and can suppress event emission. |
| `setFormat` | state: format | emit: false | Yes | Synchronizes the accepted format and can suppress event emission. |
| `setDisabled` | prop: disabled | - | No | Updates disabled state across every interactive part. |
| `setReadOnly` | prop: readOnly | - | No | Updates readonly state across editable parts. |
| `setName` | prop: name | - | No | Updates the hidden input's form field name. |
| `setOptions` | props: alpha, allowEmpty, dir, form, getAreaRoleDescription, getAriaValueText, getColorDescription, locale, required | - | No | Refreshes mutable locale, direction, accessibility, alpha, empty, and form options. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-color-picker`, `role`, `data-value`, `data-format`, `data-alpha`, `data-allow-empty`, `data-disabled`, `data-readonly`, `data-invalid`, `data-name`, `data-form`, `data-required`, `data-locale`, `dir` | Initial value, capability, form, and interaction state must be styleable before Runtime initialization. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, name, required, value |
| Hidden input | hiddenInput (text) |

### Label
Labels the color picker.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-color-picker-label` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-label` | runtime | - | Marks the Label part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| label | Yes |

### Control
Groups the visible picker controls.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-color-picker-control` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-control` | runtime | - | Marks the Control part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| control | Yes |

### Value Input
Accepts and validates a complete color string draft.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-color-picker-value-input` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-value-input` | runtime | - | Marks the Value Input part so Starwind Runtime can find it. |
| `data-invalid` | state | - | Reflects the invalid state on the Value Input part. |
#### Refs
| Part | Public |
| --- | --- |
| valueInput | Yes |

### Value Swatch
Displays the currently accepted color.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-color-picker-value-swatch` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-value-swatch` | runtime | - | Marks the Value Swatch part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| valueSwatch | Yes |

### Value Text
Displays the currently accepted color as text.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-color-picker-value-text` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-value-text` | runtime | - | Marks the Value Text part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| valueText | Yes |

### Area
Coordinates two color channels across horizontal and vertical axes.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-color-picker-area` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| xChannel | `ColorPickerChannel` | - | attribute | Selects the channel controlled by the horizontal axis. |
| yChannel | `ColorPickerChannel` | - | attribute | Selects the channel controlled by the vertical axis. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-area` | runtime | - | Marks the Area part so Starwind Runtime can find it. |
| `data-x-channel` | prop | - | Reflects the x channel prop on the Area part. |
| `data-y-channel` | prop | - | Reflects the y channel prop on the Area part. |
| `data-focused` | state | - | Reflects the focused state on the Area part. |
| `data-dragging` | state | - | Reflects the dragging state on the Area part. |
| `data-disabled` | state | - | Reflects the disabled state on the Area part. |
| `data-readonly` | state | - | Reflects the readonly state on the Area part. |
#### Refs
| Part | Public |
| --- | --- |
| area | Yes |

### Area Background
Paints the two-dimensional color-area background.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-color-picker-area-background` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-area-background` | runtime | - | Marks the Area Background part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| areaBackground | Yes |

### Area Thumb
Shows the accepted position in the color area.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-color-picker-area-thumb` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-area-thumb` | runtime | - | Marks the Area Thumb part so Starwind Runtime can find it. |
| `data-focused` | state | - | Reflects the focused state on the Area Thumb part. |
| `data-dragging` | state | - | Reflects the dragging state on the Area Thumb part. |
| `data-disabled` | state | - | Reflects the disabled state on the Area Thumb part. |
| `data-readonly` | state | - | Reflects the readonly state on the Area Thumb part. |
#### Refs
| Part | Public |
| --- | --- |
| areaThumb | Yes |

### Area Input
Provides a native range input for one color-area axis.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-color-picker-area-input` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| axis | `"x" \| "y"` | - | attribute | Selects the controlled area axis. |
| step | `number` | - | attribute | Sets the range step. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-area-input` | runtime | - | Marks the Area Input part so Starwind Runtime can find it. |
| `data-axis` | prop | - | Reflects the axis prop on the Area Input part. |
| `data-step` | prop | - | Reflects the step prop on the Area Input part. |
#### Refs
| Part | Public |
| --- | --- |
| areaInput | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-color-picker-area-input`, `type`, `data-axis`, `data-step`, `aria-roledescription`, `aria-valuetext`, `aria-description` | Both area axes expose native range semantics and accessible value context before enhancement. |

### Channel Slider
Coordinates one color channel along a horizontal or vertical track.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-color-picker-channel-slider` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| channel | `ColorPickerChannel` | - | attribute | Selects the controlled color channel. |
| orientation | `"horizontal" \| "vertical"` | "horizontal" | attribute | Sets the slider orientation. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-channel-slider` | runtime | - | Marks the Channel Slider part so Starwind Runtime can find it. |
| `data-channel` | prop | - | Reflects the channel prop on the Channel Slider part. |
| `data-orientation` | prop | - | Reflects the orientation prop on the Channel Slider part. |
| `data-focused` | state | - | Reflects the focused state on the Channel Slider part. |
| `data-dragging` | state | - | Reflects the dragging state on the Channel Slider part. |
| `data-disabled` | state | - | Reflects the disabled state on the Channel Slider part. |
| `data-readonly` | state | - | Reflects the readonly state on the Channel Slider part. |
#### Refs
| Part | Public |
| --- | --- |
| channelSlider | Yes |

### Channel Slider Track
Paints the selected channel's range.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-color-picker-channel-slider-track` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-channel-slider-track` | runtime | - | Marks the Channel Slider Track part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| channelSliderTrack | Yes |

### Channel Slider Thumb
Shows the accepted channel position.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-color-picker-channel-slider-thumb` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-channel-slider-thumb` | runtime | - | Marks the Channel Slider Thumb part so Starwind Runtime can find it. |
| `data-focused` | state | - | Reflects the focused state on the Channel Slider Thumb part. |
| `data-dragging` | state | - | Reflects the dragging state on the Channel Slider Thumb part. |
| `data-disabled` | state | - | Reflects the disabled state on the Channel Slider Thumb part. |
| `data-readonly` | state | - | Reflects the readonly state on the Channel Slider Thumb part. |
#### Refs
| Part | Public |
| --- | --- |
| channelSliderThumb | Yes |

### Channel Slider Input
Provides the native range input for a channel slider.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-color-picker-channel-input` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| step | `number` | - | attribute | Sets the range step. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-channel-input` | runtime | - | Marks the Channel Slider Input part so Starwind Runtime can find it. |
| `data-step` | prop | - | Reflects the step prop on the Channel Slider Input part. |
#### Refs
| Part | Public |
| --- | --- |
| channelSliderInput | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-color-picker-channel-input`, `type`, `data-step`, `aria-valuetext`, `aria-description` | Each visual channel slider has a keyboard-operable native range control. |

### Channel Input
Accepts and validates a numeric channel draft.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-color-picker-channel-field` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| channel | `ColorPickerChannel` | - | attribute | Selects the edited color channel. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-channel-field` | runtime | - | Marks the Channel Input part so Starwind Runtime can find it. |
| `data-channel` | prop | - | Reflects the channel prop on the Channel Input part. |
| `data-invalid` | state | - | Reflects the invalid state on the Channel Input part. |
#### Refs
| Part | Public |
| --- | --- |
| channelInput | Yes |

### Format Select
The progressively enhanced native select for hex, rgb, hsl, and hsb editing formats.
| Fact | Value |
| --- | --- |
| Default element | `select` |
| Discovery hook | `data-sw-color-picker-format-select` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-format-select` | runtime | - | Runtime discovery hook for the native format control. |
#### Refs
| Part | Public |
| --- | --- |
| formatSelect | Yes |

### Format Control
Wraps one Runtime-backed Select Root as the composite format control without reimplementing Select behavior.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-color-picker-format-control` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-format-control` | runtime | - | Runtime discovery hook for the composite format-control wrapper. |
| `data-format` | state | - | The accepted hex, rgb, hsl, or hsb editing format. |
| `data-disabled` | state | - | Present when Color Picker disables the composite Select. |
| `data-readonly` | state | - | Present when Color Picker makes the composite Select read-only. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| format | `ColorPickerFormat` | format | - | `data-format` | `getFormat` | `setFormat` | The accepted color string format used by editable and display parts. | 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. |
#### Refs
| Part | Public |
| --- | --- |
| formatControl | Yes |

### Transparency Grid
Provides a checkerboard surface beneath translucent colors.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-color-picker-transparency-grid` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-transparency-grid` | runtime | - | Marks the Transparency Grid part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| transparencyGrid | Yes |

### Swatch Group
Groups preset color swatches.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-color-picker-swatch-group` |
| Role | `group` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-swatch-group` | runtime | - | Marks the Swatch Group part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| swatchGroup | Yes |

### Swatch
Selects a preset color with native button semantics.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-color-picker-swatch` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| swatchValue | `ColorPickerValue` | - | attribute | Sets the preset color. |
| swatchDisabled | `boolean` | - | attribute | Disables this swatch. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-swatch` | runtime | - | Marks the Swatch part so Starwind Runtime can find it. |
| `data-value` | prop | - | Reflects the value prop on the Swatch part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Swatch part. |
| `data-selected` | state | - | Reflects the selected state on the Swatch part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| value | `ColorPickerColor \| null` | value | defaultValue | `data-value` | `getValue` | `setValue` | The accepted immutable color value, or null when empty values are allowed. | 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. |
#### Refs
| Part | Public |
| --- | --- |
| swatch | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-color-picker-swatch`, `type`, `data-value`, `data-disabled`, `data-selected`, `aria-pressed` | Preset selection is a native button with value, disabled, and selected semantics. |

### Eye Dropper Trigger
Opens the platform EyeDropper when that capability is available.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-color-picker-eye-dropper` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-eye-dropper` | runtime | - | Marks the Eye Dropper Trigger part so Starwind Runtime can find it. |
| `data-unsupported` | runtime | - | Marks the Eye Dropper Trigger part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| eyeDropperTrigger | Yes |

### Clear
Clears the value when empty values are allowed.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-color-picker-clear` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-clear` | runtime | - | Marks the Clear part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| clear | Yes |

### Hidden Input
The sole hidden native input used for form submission.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-color-picker-hidden-input` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-color-picker-hidden-input` | runtime | - | Marks the Hidden Input part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| hiddenInput | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-color-picker-hidden-input`, `type`, `aria-hidden`, `tabIndex`, `name`, `form`, `required`, `value` | The sole submitting control carries the canonical color string and remains programmatically focusable for native required validation while staying visually hidden, outside the tab order, and hidden from assistive technology. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, name, required, value |
| Hidden input | hiddenInput (text) |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createColorPicker`](/docs/runtime/#create-color-picker) |
| Import | `@starwind-ui/runtime/color-picker` |
| Root part | root |
| Option props | value, defaultValue, format, alpha, allowEmpty, disabled, readOnly, name, form, required, locale, dir, getAriaValueText, getAreaRoleDescription, getColorDescription, onValueChange, onValueCommitted, onFormatChange |
| Option lifecycles | 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 |
## Form Participation
| Fact | Value |
| --- | --- |
| Form props | form, name, required, value |
| Hidden input | hiddenInput (text) |
| Field integration | Yes |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Color Picker](/docs/components/color-picker/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/color-picker` | `createColorPicker` |
| Astro Primitive | `@starwind-ui/astro/color-picker` | `Color Picker`, `Color PickerRoot`, `Color PickerLabel`, `Color PickerControl`, `Color PickerValueInput`, `Color PickerValueSwatch`, `Color PickerValueText`, `Color PickerArea`, `Color PickerAreaBackground`, `Color PickerAreaThumb`, `Color PickerAreaInput`, `Color PickerChannelSlider`, `Color PickerChannelSliderTrack`, `Color PickerChannelSliderThumb`, `Color PickerChannelSliderInput`, `Color PickerChannelInput`, `Color PickerFormatSelect`, `Color PickerFormatControl`, `Color PickerTransparencyGrid`, `Color PickerSwatchGroup`, `Color PickerSwatch`, `Color PickerEyeDropperTrigger`, `Color PickerClear`, `Color PickerHiddenInput` |
| React Primitive | `@starwind-ui/react/color-picker` | `Color Picker`, `Color PickerRoot`, `Color PickerLabel`, `Color PickerControl`, `Color PickerValueInput`, `Color PickerValueSwatch`, `Color PickerValueText`, `Color PickerArea`, `Color PickerAreaBackground`, `Color PickerAreaThumb`, `Color PickerAreaInput`, `Color PickerChannelSlider`, `Color PickerChannelSliderTrack`, `Color PickerChannelSliderThumb`, `Color PickerChannelSliderInput`, `Color PickerChannelInput`, `Color PickerFormatSelect`, `Color PickerFormatControl`, `Color PickerTransparencyGrid`, `Color PickerSwatchGroup`, `Color PickerSwatch`, `Color PickerEyeDropperTrigger`, `Color PickerClear`, `Color PickerHiddenInput` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `ColorPicker` |
| runtime-factory | `createColorPicker` |
| part | `ColorPicker.Root` |
| part | `ColorPicker.Label` |
| part | `ColorPicker.Control` |
| part | `ColorPicker.ValueInput` |
| part | `ColorPicker.ValueSwatch` |
| part | `ColorPicker.ValueText` |
| part | `ColorPicker.Area` |
| part | `ColorPicker.AreaBackground` |
| part | `ColorPicker.AreaThumb` |
| part | `ColorPicker.AreaInput` |
| part | `ColorPicker.ChannelSlider` |
| part | `ColorPicker.ChannelSliderTrack` |
| part | `ColorPicker.ChannelSliderThumb` |
| part | `ColorPicker.ChannelSliderInput` |
| part | `ColorPicker.ChannelInput` |
| part | `ColorPicker.FormatSelect` |
| part | `ColorPicker.FormatControl` |
| part | `ColorPicker.TransparencyGrid` |
| part | `ColorPicker.SwatchGroup` |
| part | `ColorPicker.Swatch` |
| part | `ColorPicker.EyeDropperTrigger` |
| part | `ColorPicker.Clear` |
| part | `ColorPicker.HiddenInput` |