Color Picker

Brand color

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

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>
  );
}

Color Picker combines Starwind’s styled composition with the vendorable Color Picker Primitive and the portable createColorPicker Runtime controller. The default ColorPickerContent composition uses the composite Starwind Select format control, includes all four editing formats, and keeps form ownership on Color Picker.

Installation

pnpx starwind@latest add color-picker

npx starwind@latest add color-picker

yarn dlx starwind@latest add color-picker

Framework Availability

Astro Available React Available

Color Picker is available for Astro and React.

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.

Accent color

<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.

HEX

RGB

HSL

HSB

{(["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.

<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 when you need custom anatomy or raw adapter parts. Use the Runtime reference 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.

API Reference

Styled Component API

These props are added or materially changed by the installed Astro styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Follow the Primitive and Runtime links for lower-level behavior props.

Color Picker Root

Inherits div attributes. Omits `defaultValue`, `dir`, `onChange`, and `value`.

Contains the following additional props:

Prop Type Default

defaultValue import("@starwind-ui/runtime/color-picker").ColorPickerValue "#000000"

Description: Sets the initial value when the component is uncontrolled.
Classification: Primitive override
Primitive prop: color-picker.Root.defaultValue

dir import("@starwind-ui/runtime/color-picker").ColorPickerDirection —

Description: Sets the picker direction explicitly.
Classification: Primitive override
Primitive prop: color-picker.Root.dir

format import("@starwind-ui/runtime/color-picker").ColorPickerFormat "hex"

Description: Sets the editable color format.
Classification: Primitive override
Primitive prop: color-picker.Root.format

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Color Picker

Inherits ColorPickerRoot props.

Contains the following additional props:

Prop Type Default

closeDelay number 200

Description: Sets the delay in milliseconds before closing.
Classification: Wrapper prop

closeOnEscape boolean true

Description: Allows the surface to close when Escape is pressed.
Classification: Wrapper prop

closeOnOutsideInteract boolean true

Description: Allows the surface to close after an outside interaction.
Classification: Wrapper prop

defaultOpen boolean false

Description: Sets the initial open state when the component is uncontrolled.
Classification: Wrapper prop

modal boolean false

Description: Controls whether interaction outside the surface is blocked while open.
Classification: Wrapper prop

openOnHover boolean false

Description: Allows pointer hover to open the surface.
Classification: Wrapper prop

Color Picker Label

Inherits label attributes.

Contains the following additional props:

Prop Type Default

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Color Picker Control

Inherits div attributes.

Contains the following additional props:

Prop Type Default

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Color Picker Input

Inherits div attributes.

Contains the following additional props:

Prop Type Default

formatControl "select" | "native" "select"

Description: Chooses the composite Select or progressively enhanced native format control.
Classification: Wrapper prop

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Color Picker Trigger

Inherits PopoverTrigger props.

Contains the following additional props:

Prop Type Default

showValueText boolean true

Description: Shows the formatted value beside the trigger swatch.
Classification: Wrapper prop

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Color Picker Content

Inherits PopoverContent props.

Contains the following additional props:

Prop Type Default

alpha boolean true

Description: Includes alpha controls in the picker content.
Classification: Wrapper prop

showClear boolean false

Description: Shows the generated clear-value control.
Classification: Wrapper prop

showEyeDropper boolean true

Description: Shows the EyeDropper trigger when supported.
Classification: Wrapper prop

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Color Picker Area

Inherits div attributes.

Contains the following additional props:

Prop Type Default

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Color Picker Area Thumb

Inherits span attributes.

Contains the following additional props:

Prop Type Default

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Color Picker Sliders

Inherits div attributes.

Contains the following additional props:

Prop Type Default

alpha boolean true

Description: Includes an alpha channel slider.
Classification: Wrapper prop

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Color Picker Channel Slider

Inherits div attributes.

Contains the following additional props:

Prop Type Default

channel Required import("@starwind-ui/runtime/color-picker").ColorPickerChannel —

Description: Selects the channel rendered by this slider.
Classification: Primitive override
Primitive prop: color-picker.ChannelSlider.channel

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Color Picker Channel Input

Inherits input attributes.

Contains the following additional props:

Prop Type Default

channel Required import("@starwind-ui/runtime/color-picker").ColorPickerChannel —

Description: Selects the channel edited by this input.
Classification: Primitive override
Primitive prop: color-picker.ChannelInput.channel

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Color Picker Value Input

Inherits input attributes. Omits `size`.

Contains the following additional props:

Prop Type Default

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Color Picker Native Format Select

Inherits select attributes. Omits `size`.

Contains the following additional props:

Prop Type Default

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Color Picker Format Select

Inherits div attributes.

Contains the following additional props:

Prop Type Default

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Wrapper prop

Color Picker Value Swatch

Inherits span attributes.

Contains the following additional props:

Prop Type Default

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Color Picker Swatch Group

Inherits div attributes.

Contains the following additional props:

Prop Type Default

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Color Picker Swatch

Inherits button attributes.

Contains the following additional props:

Prop Type Default

disabled boolean false

Description: Disables interaction with the component.
Classification: Wrapper prop

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

value Required import("@starwind-ui/runtime/color-picker").ColorPickerValue —

Description: Controls or identifies the component value.
Classification: Wrapper prop

Color Picker Eye Dropper

Inherits button attributes.

Contains the following additional props:

Prop Type Default

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Color Picker Clear

Inherits button attributes.

Contains the following additional props:

Prop Type Default

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Color Picker Hidden Input

Inherits input attributes.

Contains the following additional props:

Prop Type Default

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Primitive And Runtime API

Use these references when you need the lower-level behavior APIs behind Color Picker.

Primitive API

Color Picker Primitive

Runtime API

Color Picker primitive: createColorPicker 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 for the underlying unstyled anatomy and behavior API.

Layer Metadata

Color Picker uses the Color Picker primitive for its behavior foundation. Color Picker is available for Astro and React.

styled-component Color Picker Color Picker uses the Color Picker primitive for its behavior foundation. Color Picker is available for Astro and React. Styled component Behavior Foundation color-picker direct-primitive Direct primitive /docs/components/color-picker/ ColorPicker ColorPickerRoot ColorPickerLabel ColorPickerControl ColorPickerInput ColorPickerTrigger ColorPickerContent ColorPickerArea ColorPickerAreaThumb ColorPickerSliders ColorPickerChannelSlider ColorPickerChannelInput ColorPickerValueInput ColorPickerNativeFormatSelect ColorPickerFormatSelect ColorPickerValueSwatch ColorPickerSwatchGroup ColorPickerSwatch ColorPickerEyeDropper ColorPickerClear ColorPickerHiddenInput Root InlineRoot Label Control Input Trigger Content Area AreaThumb Sliders ChannelSlider ChannelInput ValueInput NativeFormatSelect FormatSelect ValueSwatch SwatchGroup Swatch EyeDropper Clear HiddenInput ColorPickerVariants Form & Input forms inputs controls astro react colorPicker colorPickerAction colorPickerArea colorPickerAreaThumb colorPickerChannelInputLayout colorPickerChannelSlider colorPickerChannelSliderThumb colorPickerContent colorPickerControl colorPickerFormatSelectTrigger colorPickerHiddenInput colorPickerInput colorPickerLabel colorPickerSeparator colorPickerSliderActionRow colorPickerSliders colorPickerSwatch colorPickerSwatchGroup colorPickerTrigger colorPickerValueFormatRow colorPickerValueInputLayout colorPickerValueSwatch color-picker-area color-picker-area-background color-picker-area-input-x color-picker-area-input-y color-picker-area-thumb color-picker-channel-input color-picker-channel-slider color-picker-channel-slider-input color-picker-channel-slider-thumb color-picker-channel-slider-track color-picker-channel-thumb-color-layer color-picker-clear color-picker-content color-picker-control color-picker-eye-dropper color-picker-footer color-picker-format-control color-picker-hidden-input color-picker-input color-picker-label color-picker-native-format-select color-picker-native-format-select-icon color-picker-native-format-select-wrapper color-picker-separator color-picker-slider-action-row color-picker-sliders color-picker-swatch color-picker-swatch-color color-picker-swatch-group color-picker-transparency-grid color-picker-trigger color-picker-value-format-row color-picker-value-input color-picker-value-swatch color-picker-value-swatch-color color-picker-value-text /docs/primitives/color-picker/ Primitive Color Picker createColorPicker @starwind-ui/runtime/color-picker /docs/runtime/#create-color-picker Runtime factory createColorPicker Astro available Available Astro available React React available defaultValue import("@starwind-ui/runtime/color-picker").ColorPickerValue Primitive override "#000000" Sets the initial value when the component is uncontrolled. dir import("@starwind-ui/runtime/color-picker").ColorPickerDirection Sets the picker direction explicitly. format import("@starwind-ui/runtime/color-picker").ColorPickerFormat "hex" Sets the editable color format. size "sm" | "md" | "lg" Styled variant "md" Selects the component's visual size. sm md lg div attributes closeDelay number Wrapper prop 200 Sets the delay in milliseconds before closing. closeOnEscape boolean true Allows the surface to close when Escape is pressed. closeOnOutsideInteract Allows the surface to close after an outside interaction. defaultOpen false Sets the initial open state when the component is uncontrolled. modal Controls whether interaction outside the surface is blocked while open. openOnHover Allows pointer hover to open the surface. ColorPickerRoot props label attributes formatControl "select" | "native" "select" Chooses the composite Select or progressively enhanced native format control. showValueText Shows the formatted value beside the trigger swatch. PopoverTrigger props alpha Includes alpha controls in the picker content. showClear Shows the generated clear-value control. showEyeDropper Shows the EyeDropper trigger when supported. PopoverContent props span attributes Includes an alpha channel slider. channel import("@starwind-ui/runtime/color-picker").ColorPickerChannel Selects the channel rendered by this slider. Selects the channel edited by this input. input attributes select attributes disabled Disables interaction with the component. value Controls or identifies the component value. button attributes