Skip to main content

Starwind UI v3.0 is now available! Migration guide

Color Picker

Brand color

ColorPicker renders a complete popover editor when it has no children. The default editor includes the color area, hue and alpha sliders, exact value input, styled format selector, EyeDropper action, and any supplied swatches. It also appends the hidden form input automatically.

Installation

To vendor the unstyled adapter source for raw anatomy customization, run starwind primitives add color-picker. The Runtime controller reference documents the underlying behavior API.

Usage

---
import { ColorPicker } from "@/components/starwind/color-picker";
const swatches = [
{ value: "#ef4444", label: "Red" },
{ value: "#f59e0b", label: "Amber" },
{ value: "#10b981", label: "Emerald" },
{ value: "#0ea5e9", label: "Sky" },
{ value: "#8b5cf6", label: "Violet" },
];
---
<ColorPicker
label="Brand color"
name="brand-color"
defaultValue="#ff000080"
alpha
swatches={swatches}
/>

Sizes

ColorPicker owns trigger-side and inline anatomy. ColorPickerContent independently owns the portaled editor, because it cannot inherit styling state across the portal boundary. Both scopes accept sm, md (the default), or lg. Default composition passes the root size to its owned content automatically.

ColorPickerInput accepts formatContentSize only for its nested Select popup. Use it when a custom editor needs that second portal to differ from the editor scope.

Small

Compact brand color

Large

Large accent color

Independent popup size

Respond to Color Changes

Use value changes for immediate UI such as previews. In React, control the picker with value and onValueChange. In Astro, listen for starwind:value-change on the root and read event.detail.valueAsString.

For work that should happen only after an interaction finishesโ€”such as persisting a preferenceโ€”use Reactโ€™s onValueCommitted or Astroโ€™s starwind:value-committed event instead.

Preview color
#4f46e5

Inline Editor

Set inline when people benefit from seeing the full editor without opening a popover, such as in a theme builder or design settings panel.

Theme accent

Used for links, focus rings, and primary actions.

Accent color

Format Controls and Optional Features

  • format accepts "hex", "rgb", "hsl", or "hsb" and defaults to "hex".
  • formatControl="select" uses the styled selector and is the default. Use "native" for a browser <select> or "none" to omit the selector.
  • formats limits the available formats. Duplicate entries are removed, and the active format remains available even if it was omitted from the array.
  • alpha defaults to true. Set alpha={false} when transparency is not valid.
  • showEyeDropper defaults to true. The action also hides automatically when the browser or security context does not support the EyeDropper API.
  • showValueText={false} creates a swatch-only default trigger.
  • clearable allows an empty value and adds the default Clear action. It replaces the old styled allowEmpty and showClear combination.
  • swatches accepts color strings or { value, label, disabled? } objects. String swatches use the color value as their accessible label.
---
import { ColorPicker } from "@/components/starwind/color-picker";
---
<ColorPicker
label="Accent color"
defaultValue="rgb(37, 99, 235)"
formats={["rgb", "hex"]}
formatControl="native"
alpha={false}
showEyeDropper={false}
clearable
/>

Forms and Reset

Put name, form, and required directly on ColorPicker. Its automatic hidden input owns the submitted value, native validity, and form association. Resetting the form restores the initial color and format.

Accent color
Not submitted

Custom Composition

Supplying children replaces the visible default editor. Use this for authored trigger layouts, input-only pickers, swatch-only triggers, or custom channel arrangements. The hidden form input is still appended automatically.

---
import {
ColorPicker,
ColorPickerContent,
ColorPickerTrigger,
} from "@/components/starwind/color-picker";
---
<ColorPicker label="Brand color" defaultValue="#0ea5e9">
{(initial) => (
<>
<span class="text-sm font-medium" data-slot="color-picker-label">Brand color</span>
<ColorPickerTrigger
initial={initial}
showValueText={false}
aria-label="Open brand color picker"
/>
<ColorPickerContent initial={initial} aria-label="Brand color editor" />
</>
)}
</ColorPicker>

Use ColorPickerArea, ColorPickerChannelSlider, ColorPickerChannelInput, ColorPickerInput, ColorPickerValueSwatch, ColorPickerSwatchGroup, ColorPickerSwatch, ColorPickerEyeDropper, and ColorPickerClear for more specialized compositions. Use the Primitive reference when you need to replace only an internal area thumb, format-selector part, or hidden input.

Migrate the Previous Styled API

Previous APIReplacement
ColorPickerRoot<ColorPicker inline>
ColorPickerLabelThe label prop or an authored label
ColorPickerControlThe default wrapper or an authored container
ColorPickerAreaThumbIncluded by ColorPickerArea
ColorPickerSlidersThe default editor or explicit channel sliders
ColorPickerValueInput<ColorPickerInput formatControl="none" />
Native or styled format-select partsColorPickerInput or the root formatControl prop
ColorPickerHiddenInputAutomatically rendered by ColorPicker
allowEmpty plus showClearclearable
Content swatch slot or React nodeThe root or content swatches array
Inner anatomy size propsSet size on ColorPicker or ColorPickerContent
ColorPickerInput sizeColorPickerInput formatContentSize for its nested Select popup

Accessibility

  • Use label for the common composition or author an accessible label for a custom layout.
  • Keep the area and channel controls available so the editor remains keyboard operable.
  • Give object swatches names that identify the choice; do not rely on color alone.
  • Preserve visible focus styles and sufficient contrast around thumbs, swatches, and controls in custom themes.
  • Use required, disabled, and readOnly according to the formโ€™s intent.

API Reference

Styled Component API

These props are added or materially changed by the installed styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Expand a prop to see named type definitions and framework-specific imports. Follow the Primitive and Runtime links for lower-level behavior props.

Color Picker

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

Contains the following additional props:

Prop Type Default Toggle details
align "start" | "center" | "end" "start"
Description
Aligns the component within its available axis.
Classification
Wrapper prop
avoidCollisions boolean true
Description
Repositions floating content to keep it inside the collision boundary.
Classification
Wrapper prop
clearable boolean false
Description
Allows an empty value and includes the default Clear action.
Classification
Wrapper prop
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
defaultValue string | ColorPickerColor | null "#000000"
Description
Sets the initial value when the component is uncontrolled.
Classification
Primitive override
Type definition
type ColorPickerValue = string | ColorPickerColor | null;
Type imports
Astro import type { ColorPickerValue } from "@starwind-ui/astro/color-picker";
React import type { ColorPickerValue } from "@starwind-ui/react/color-picker";
Primitive prop
color-picker.Root.defaultValue
dir "ltr" | "rtl" โ€”
Description
Sets the picker direction explicitly.
Classification
Primitive override
Type definition
type ColorPickerDirection = "ltr" | "rtl";
Type imports
Astro import type { ColorPickerDirection } from "@starwind-ui/astro/color-picker";
React import type { ColorPickerDirection } from "@starwind-ui/react/color-picker";
Primitive prop
color-picker.Root.dir
disablePortal boolean false
Description
Keeps the public Portal wrapper inline instead of moving it to a target.
Classification
Wrapper prop
format "hex" | "rgb" | "hsl" | "hsb" โ€”
Description
Sets the editable color format.
Classification
Wrapper prop
Type definition
type ColorPickerFormat = "hex" | "rgb" | "hsl" | "hsb";
Type imports
Astro import type { ColorPickerFormat } from "@starwind-ui/astro/color-picker";
React import type { ColorPickerFormat } from "@starwind-ui/react/color-picker";
formatControl "select" | "native" | "none" "select"
Description
Chooses a styled, native, or absent format control.
Classification
Wrapper prop
formats readonly ColorPickerFormat[] ["hex","rgb","hsl","hsb"]
Description
Restricts and orders the available color formats.
Classification
Wrapper prop
Type definition
type ColorPickerFormat = "hex" | "rgb" | "hsl" | "hsb";
Type imports
Astro import type { ColorPickerFormat } from "@starwind-ui/astro/color-picker";
React import type { ColorPickerFormat } from "@starwind-ui/react/color-picker";
inline boolean false
Description
Renders the complete editor without a Popover shell.
Classification
Wrapper prop
label string โ€”
Description
Provides accessible text for the component.
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
portalContainer string โ€”
Description
Sets the CSS selector for the public Portal wrapper target.
Classification
Wrapper prop
showEyeDropper boolean true
Description
Shows the EyeDropper trigger when supported.
Classification
Wrapper prop
showValueText boolean true
Description
Shows the formatted value beside the trigger swatch.
Classification
Wrapper prop
side "top" | "right" | "bottom" | "left" "bottom"
Description
Selects the preferred side for floating content.
Classification
Wrapper prop
sideOffset number 4
Description
Sets the distance in pixels between floating content and its anchor.
Classification
Wrapper prop
size "sm" | "md" | "lg" "md"
Description
Selects the component's visual size.
Classification
Styled variant
swatches readonly (ColorPickerValue | { value: ColorPickerValue; label: string; disabled?: boolean })[] []
Description
Adds suggested colors to the default editor.
Classification
Wrapper prop
Type definition
type ColorPickerValue = string | ColorPickerColor | null;
Type imports
Astro import type { ColorPickerValue } from "@starwind-ui/astro/color-picker";
React import type { ColorPickerValue } from "@starwind-ui/react/color-picker";

Color Picker Input

Inherits div attributes.

Contains the following additional props:

Prop Type Default Toggle details
disablePortal boolean false
Description
Keeps the public Portal wrapper inline instead of moving it to a target.
Classification
Wrapper prop
formatContentSize "sm" | "md" | "lg" "md"
Description
Sets the independently portaled format Select popup size.
Classification
Wrapper prop
formatControl "select" | "native" | "none" "select"
Description
Chooses a styled, native, or absent format control.
Classification
Wrapper prop
formats readonly ColorPickerFormat[] ["hex","rgb","hsl","hsb"]
Description
Restricts and orders the available color formats.
Classification
Wrapper prop
Type definition
type ColorPickerFormat = "hex" | "rgb" | "hsl" | "hsb";
Type imports
Astro import type { ColorPickerFormat } from "@starwind-ui/astro/color-picker";
React import type { ColorPickerFormat } from "@starwind-ui/react/color-picker";
portalContainer string โ€”
Description
Sets the CSS selector for the public Portal wrapper target.
Classification
Wrapper prop

Color Picker Trigger

Inherits PopoverTrigger props.

Contains the following additional props:

Prop Type Default Toggle details
showValueText boolean true
Description
Shows the formatted value beside the trigger swatch.
Classification
Wrapper prop

Color Picker Content

Inherits PopoverContent props.

Contains the following additional props:

Prop Type Default Toggle details
formatControl "select" | "native" | "none" "select"
Description
Chooses a styled, native, or absent format control.
Classification
Wrapper prop
formats readonly ColorPickerFormat[] ["hex","rgb","hsl","hsb"]
Description
Restricts and orders the available color formats.
Classification
Wrapper prop
Type definition
type ColorPickerFormat = "hex" | "rgb" | "hsl" | "hsb";
Type imports
Astro import type { ColorPickerFormat } from "@starwind-ui/astro/color-picker";
React import type { ColorPickerFormat } from "@starwind-ui/react/color-picker";
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
swatches readonly (ColorPickerValue | { value: ColorPickerValue; label: string; disabled?: boolean })[] []
Description
Provides suggested values for the generated swatch group.
Classification
Wrapper prop
Type definition
type ColorPickerValue = string | ColorPickerColor | null;
Type imports
Astro import type { ColorPickerValue } from "@starwind-ui/astro/color-picker";
React import type { ColorPickerValue } from "@starwind-ui/react/color-picker";

Color Picker Channel Slider

Inherits div attributes.

Contains the following additional props:

Prop Type Default Toggle details
channel Required "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue" | "alpha" โ€”
Description
Selects the channel rendered by this slider.
Classification
Primitive override
Type definition
type ColorPickerChannel = "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue" | "alpha";
Type imports
Astro import type { ColorPickerChannel } from "@starwind-ui/astro/color-picker";
React import type { ColorPickerChannel } from "@starwind-ui/react/color-picker";
Primitive prop
color-picker.ChannelSlider.channel

Color Picker Channel Input

Inherits input attributes.

Contains the following additional props:

Prop Type Default Toggle details
channel Required "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue" | "alpha" โ€”
Description
Selects the channel edited by this input.
Classification
Primitive override
Type definition
type ColorPickerChannel = "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue" | "alpha";
Type imports
Astro import type { ColorPickerChannel } from "@starwind-ui/astro/color-picker";
React import type { ColorPickerChannel } from "@starwind-ui/react/color-picker";
Primitive prop
color-picker.ChannelInput.channel

Color Picker Swatch

Inherits button attributes. Omits `value`.

Contains the following additional props:

Prop Type Default Toggle details
disabled boolean false
Description
Disables interaction with the component.
Classification
Wrapper prop
value Required string | ColorPickerColor | null โ€”
Description
Controls or identifies the component value.
Classification
Wrapper prop
Type definition
type ColorPickerValue = string | ColorPickerColor | null;
Type imports
Astro import type { ColorPickerValue } from "@starwind-ui/astro/color-picker";
React import type { ColorPickerValue } from "@starwind-ui/react/color-picker";

Primitive And Runtime API

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

Runtime API

Color Picker primitive
createColorPicker from @starwind-ui/runtime/color-picker

Changelog

View version history v2.1.0 5 releases

v2.1.0

  • Added portalContainer and disablePortal to the root and content APIs for custom portal targets and inline rendering, including the nested format selector.

v2.0.2

  • Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.
  • Accepted raw color values and labeled descriptors in generated Astro and React swatch arrays without JavaScript or TypeScript compile errors.
  • Applied the configured format selection before first interaction in React so controls such as HEX show their selected styling immediately.

v2.0.1

  • Removed unused generated bindings from the Astro and React components so strict consumer builds pass without unused import or local errors.

v2.0.0

  • Adopted Tailwind CSS v4 custom-property shorthand throughout the installed component classes; this is a source-level cleanup with no API or visual change.
  • Simplified the styled API around a complete zero-child popup or inline editor.
  • Centralized visual sizing on ColorPicker and independently portaled ColorPickerContent, both defaulting to md; default composition forwards the root size to its owned content.
  • Removed size from inner anatomy. Move it to the owning root/content scope, or replace ColorPickerInput size with formatContentSize when sizing only the nested format popup.
  • Added convenience props for labels, format controls, format lists, EyeDropper visibility, value text, clearing, and swatch data while keeping alpha enabled by default.
  • Folded labels, control wrappers, area thumbs, sliders, format selectors, value inputs, and hidden form inputs into their owning components.
  • Custom children now replace the visible default anatomy; use the Color Picker Primitive for raw anatomy customization.

v0.1.0

  • Added the Runtime-backed Astro and React Color Picker with popup and inline compositions, alpha, swatches, HEX, RGB, HSL, and HSB editing, and native form participation.