# Color Picker

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  ColorPicker,
  ColorPickerContent,
  ColorPickerControl,
  ColorPickerHiddenInput,
  ColorPickerLabel,
  ColorPickerSwatch,
  ColorPickerSwatchGroup,
  ColorPickerTrigger,
} from "@/components/starwind/color-picker";
---

<ColorPicker defaultValue="#ff000080" format="hex" alpha name="brand-color">
  {(initial) => (
    <>
      <ColorPickerLabel initial={initial.label.initial}>Brand color</ColorPickerLabel>
      <ColorPickerControl initial={initial.control.initial}>
        <ColorPickerTrigger initial={initial} showValueText />
      </ColorPickerControl>
      <ColorPickerContent initial={initial}>
        <ColorPickerSwatchGroup
          slot="swatches"
          initial={initial.swatchGroup.initial}
          aria-label="Suggested brand colors"
        >
          <ColorPickerSwatch initial={initial} value="#ef4444" aria-label="Red swatch" />
          <ColorPickerSwatch initial={initial} value="#f59e0b" aria-label="Amber swatch" />
          <ColorPickerSwatch initial={initial} value="#10b981" aria-label="Emerald swatch" />
          <ColorPickerSwatch initial={initial} value="#0ea5e9" aria-label="Sky swatch" />
          <ColorPickerSwatch initial={initial} value="#8b5cf6" aria-label="Violet swatch" />
        </ColorPickerSwatchGroup>
      </ColorPickerContent>
      <ColorPickerHiddenInput initial={initial.hiddenInput.initial} />
    </>
  )}
</ColorPicker>
```
  </div>
  <div slot="react">
```tsx
import {
  ColorPicker,
  ColorPickerContent,
  ColorPickerControl,
  ColorPickerHiddenInput,
  ColorPickerLabel,
  ColorPickerSwatch,
  ColorPickerSwatchGroup,
  ColorPickerTrigger,
} from "@/components/starwind/color-picker";

export function Example() {
  return (
    <ColorPicker defaultValue="#ff000080" format="hex" alpha name="brand-color">
      <ColorPickerLabel>Brand color</ColorPickerLabel>
      <ColorPickerControl>
        <ColorPickerTrigger showValueText />
      </ColorPickerControl>
      <ColorPickerContent>
        <ColorPickerSwatchGroup aria-label="Suggested brand colors">
          <ColorPickerSwatch value="#ef4444" aria-label="Red swatch" />
          <ColorPickerSwatch value="#f59e0b" aria-label="Amber swatch" />
          <ColorPickerSwatch value="#10b981" aria-label="Emerald swatch" />
          <ColorPickerSwatch value="#0ea5e9" aria-label="Sky swatch" />
          <ColorPickerSwatch value="#8b5cf6" aria-label="Violet swatch" />
        </ColorPickerSwatchGroup>
      </ColorPickerContent>
      <ColorPickerHiddenInput />
    </ColorPicker>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

Color Picker combines Starwind's styled composition with the vendorable [Color Picker
Primitive](/docs/primitives/color-picker/) and the portable [`createColorPicker` Runtime
controller](/docs/runtime/#create-color-picker). The default `ColorPickerContent` composition uses
the composite Starwind Select format control, includes all four editing formats, and keeps form
ownership on Color Picker.

## Installation

```bash
npx starwind@latest add color-picker
```

The `0.1.0` styled component installs its Popover, Select, and Native Select dependencies. To own
the Primitive adapter source too, run `starwind primitives add color-picker`.

## Usage

### Native format control

`ColorPickerInput` uses the composite `ColorPickerFormatSelect` by default. Set
`formatControl="native"` to render `ColorPickerNativeFormatSelect` for browser-native interaction
and progressive enhancement. Both controls edit the same Color Picker format state and neither
creates a second submitted form value.

```astro
<ColorPickerRoot defaultValue="rgb(37, 99, 235)" format="rgb" alpha={false}>
  {(initial) => (
    <>
      <ColorPickerLabel initial={initial.label.initial}>Accent color</ColorPickerLabel>
      <ColorPickerInput initial={initial} formatControl="native" />
      <ColorPickerHiddenInput initial={initial.hiddenInput.initial} />
    </>
  )}
</ColorPickerRoot>
```

### Four color formats

Color Picker supports `hex`, `rgb`, `hsl`, and `hsb`. The value input, selected format, area,
channel controls, swatches, CSS thumb colors, and hidden form value stay synchronized after each
accepted edit.

```astro
{(["hex", "rgb", "hsl", "hsb"] as const).map((format) => (
  <ColorPickerRoot defaultValue="#2563eb" format={format} alpha={false}>
    {(initial) => (
      <>
        <ColorPickerLabel initial={initial.label.initial}>{format.toUpperCase()}</ColorPickerLabel>
        <ColorPickerInput
          initial={initial}
          formatControl={format === "rgb" ? "native" : "select"}
        />
      </>
    )}
  </ColorPickerRoot>
))}
```

### Forms and state

Put `name`, `form`, and `required` on `ColorPicker` or `ColorPickerRoot`, then render one
`ColorPickerHiddenInput`. It is the sole submitted field. Native form reset restores the initial
value and format; `disabled` prevents interaction and submission, while `readOnly` preserves the
value without allowing edits. To offer the advanced Clear action, explicitly pair root
`allowEmpty` with `showClear` on `ColorPickerContent`; `showClear` does not enable empty values by
itself.

```astro
<form>
<ColorPicker
  defaultValue="#2563eb"
    format="hex"
    allowEmpty
    required
    name="accent"
  >
    {(initial) => (
      <>
        <ColorPickerLabel initial={initial.label.initial}>Required accent</ColorPickerLabel>
        <ColorPickerControl initial={initial.control.initial}>
          <ColorPickerTrigger initial={initial} showValueText />
        </ColorPickerControl>
        <ColorPickerContent initial={initial} showClear />
        <ColorPickerHiddenInput initial={initial.hiddenInput.initial} />
      </>
    )}
  </ColorPicker>
  <button type="submit">Submit color</button>
  <button type="reset">Reset color</button>
</form>
```

### Anatomy

- `ColorPicker` composes the floating Popover; use `ColorPickerRoot` for an inline editor.
- `ColorPickerLabel`, `ColorPickerControl`, and `ColorPickerTrigger` form the closed control.
- `ColorPickerContent` provides the canonical area, channel sliders, value input, format control,
optional actions, separator, and consumer swatch slot.
- `ColorPickerValueInput` is the standalone exact-value editor.
- `ColorPickerFormatSelect` is the composite Select path;
`ColorPickerNativeFormatSelect` is the native path.
- `ColorPickerSwatchGroup` and `ColorPickerSwatch` provide preset choices.
- `ColorPickerHiddenInput` owns native form submission, validity, form association, and reset.

Use the [Primitive reference](/docs/primitives/color-picker/) when you need custom anatomy or raw
adapter parts. Use the [Runtime reference](/docs/runtime/#create-color-picker) for controller state,
events, setters, and raw HTML initialization.

## Accessibility

- Give every picker a visible `ColorPickerLabel` or an equivalent accessible name.
- Keep the generated range inputs available so area and channel editing remains keyboard operable.
- The composite format control owns combobox/listbox semantics; the native option uses a labeled
`<select>`. Do not render both choices for one user-facing format control.
- Swatches are buttons with selected state, and the popup returns focus to its trigger on Escape.
- Use `required`, `disabled`, and `readOnly` according to form intent, and do not communicate state
through color alone.
- Preserve visible focus styles and sufficient contrast around thumbs, swatches, and controls in
custom themes.

## Framework Availability
Color Picker is available for Astro and React.
Astro available; React available
| Framework | Status | Notes |
| --- | --- | --- |
| Astro | available | - |
| React | available | - |
## API Reference
### ColorPickerRoot
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `defaultValue` | `import("@starwind-ui/runtime/color-picker").ColorPickerValue` | No | `"#000000"` | Primitive override | Sets the initial value when the component is uncontrolled. |
| `dir` | `import("@starwind-ui/runtime/color-picker").ColorPickerDirection` | No | - | Primitive override | Sets the picker direction explicitly. |
| `format` | `import("@starwind-ui/runtime/color-picker").ColorPickerFormat` | No | `"hex"` | Primitive override | Sets the editable color format. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits div attributes. Omits `defaultValue`, `dir`, `onChange`, and `value`.

### ColorPicker
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `closeDelay` | `number` | No | `200` | Wrapper prop | Sets the delay in milliseconds before closing. |
| `closeOnEscape` | `boolean` | No | `true` | Wrapper prop | Allows the surface to close when Escape is pressed. |
| `closeOnOutsideInteract` | `boolean` | No | `true` | Wrapper prop | Allows the surface to close after an outside interaction. |
| `defaultOpen` | `boolean` | No | `false` | Wrapper prop | Sets the initial open state when the component is uncontrolled. |
| `modal` | `boolean` | No | `false` | Wrapper prop | Controls whether interaction outside the surface is blocked while open. |
| `openOnHover` | `boolean` | No | `false` | Wrapper prop | Allows pointer hover to open the surface. |
- Inherits ColorPickerRoot props.

### ColorPickerLabel
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits label attributes.

### ColorPickerControl
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits div attributes.

### ColorPickerInput
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `formatControl` | `"select" \| "native"` | No | `"select"` | Wrapper prop | Chooses the composite Select or progressively enhanced native format control. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits div attributes.

### ColorPickerTrigger
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `showValueText` | `boolean` | No | `true` | Wrapper prop | Shows the formatted value beside the trigger swatch. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits PopoverTrigger props.

### ColorPickerContent
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `alpha` | `boolean` | No | `true` | Wrapper prop | Includes alpha controls in the picker content. |
| `showClear` | `boolean` | No | `false` | Wrapper prop | Shows the generated clear-value control. |
| `showEyeDropper` | `boolean` | No | `true` | Wrapper prop | Shows the EyeDropper trigger when supported. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits PopoverContent props.

### ColorPickerArea
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits div attributes.

### ColorPickerAreaThumb
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits span attributes.

### ColorPickerSliders
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `alpha` | `boolean` | No | `true` | Wrapper prop | Includes an alpha channel slider. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits div attributes.

### ColorPickerChannelSlider
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `channel` | `import("@starwind-ui/runtime/color-picker").ColorPickerChannel` | Yes | - | Primitive override | Selects the channel rendered by this slider. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits div attributes.

### ColorPickerChannelInput
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `channel` | `import("@starwind-ui/runtime/color-picker").ColorPickerChannel` | Yes | - | Primitive override | Selects the channel edited by this input. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits input attributes.

### ColorPickerValueInput
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits input attributes. Omits `size`.

### ColorPickerNativeFormatSelect
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits select attributes. Omits `size`.

### ColorPickerFormatSelect
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Wrapper prop | Selects the component's visual size. |
- Inherits div attributes.

### ColorPickerValueSwatch
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits span attributes.

### ColorPickerSwatchGroup
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits div attributes.

### ColorPickerSwatch
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `disabled` | `boolean` | No | `false` | Wrapper prop | Disables interaction with the component. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
| `value` | `import("@starwind-ui/runtime/color-picker").ColorPickerValue` | Yes | - | Wrapper prop | Controls or identifies the component value. |
- Inherits button attributes.

### ColorPickerEyeDropper
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits button attributes.

### ColorPickerClear
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits button attributes.

### ColorPickerHiddenInput
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits input attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Color Picker Primitive](/docs/primitives/color-picker/)
- Runtime factory: [`createColorPicker`](/docs/runtime/#create-color-picker) from `@starwind-ui/runtime/color-picker`

## Changelog

### v0.1.0

- Added the Runtime-backed Astro and React Color Picker with composite and native format controls, all four color formats, alpha, swatches, nullable values, and native form participation.
- Established the canonical styled composition with a no-Clear default; advanced Clear usage explicitly pairs root `allowEmpty` with content `showClear`.
- See the [Color Picker Primitive](/docs/primitives/color-picker/) for the underlying unstyled anatomy and behavior API.