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". When you pass formats without format, the picker starts on the first listed format in every framework.
  • 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.

In Svelte, value and format follow the same rule as every other Svelte model. If you pass a defined first value, your state owns it and a form reset keeps it. If the first value is undefined, the picker owns it, and a later defined value from your state sets it. See Svelte usage for the rule.

---
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";
initial ColorPickerRenderProjection —
Description
Supplies the Astro server-render projection for this Color Picker part before browser initialization.
Classification
Wrapper prop
Type imports
Astro import type { ColorPickerRenderProjection } from "@starwind-ui/astro/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
initial ColorPickerRenderProjection —
Description
Supplies the Astro server-render projection for this Color Picker part before browser initialization.
Classification
Wrapper prop
Type imports
Astro import type { ColorPickerRenderProjection } from "@starwind-ui/astro/color-picker";
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";
initial ColorPickerRenderProjection —
Description
Supplies the Astro server-render projection for this Color Picker part before browser initialization.
Classification
Wrapper prop
Type imports
Astro import type { ColorPickerRenderProjection } from "@starwind-ui/astro/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 Area

Inherits div attributes.

Contains the following additional props:

Prop Type Default Toggle details
initial ColorPickerAreaProjection —
Description
Supplies the Astro server-render projection for this Color Picker part before browser initialization.
Classification
Wrapper prop
Type imports
Astro import type { ColorPickerAreaProjection } from "@starwind-ui/astro/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
initial ColorPickerRenderProjection —
Description
Supplies the Astro server-render projection for this Color Picker part before browser initialization.
Classification
Wrapper prop
Type imports
Astro import type { ColorPickerRenderProjection } from "@starwind-ui/astro/color-picker";
step number —
Description
Sets the smallest allowed value increment.
Classification
Wrapper prop

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
initial ColorPickerInitialPartProjection —
Description
Supplies the Astro server-render projection for this Color Picker part before browser initialization.
Classification
Wrapper prop
Type imports
Astro import type { ColorPickerInitialPartProjection } from "@starwind-ui/astro/color-picker";

Color Picker Value Swatch

Inherits span attributes.

Contains the following additional props:

Prop Type Default Toggle details
initial ColorPickerRenderProjection —
Description
Supplies the Astro server-render projection for this Color Picker part before browser initialization.
Classification
Wrapper prop
Type imports
Astro import type { ColorPickerRenderProjection } from "@starwind-ui/astro/color-picker";

Color Picker Swatch Group

Inherits div attributes.

Contains the following additional props:

Prop Type Default Toggle details
initial ColorPickerInitialPartProjection —
Description
Supplies the Astro server-render projection for this Color Picker part before browser initialization.
Classification
Wrapper prop
Type imports
Astro import type { ColorPickerInitialPartProjection } from "@starwind-ui/astro/color-picker";

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
initial ColorPickerRenderProjection —
Description
Supplies the Astro server-render projection for this Color Picker part before browser initialization.
Classification
Wrapper prop
Type imports
Astro import type { ColorPickerRenderProjection } from "@starwind-ui/astro/color-picker";
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";

Color Picker Eye Dropper

Inherits button attributes.

Contains the following additional props:

Prop Type Default Toggle details
initial ColorPickerInitialPartProjection —
Description
Supplies the Astro server-render projection for this Color Picker part before browser initialization.
Classification
Wrapper prop
Type imports
Astro import type { ColorPickerInitialPartProjection } from "@starwind-ui/astro/color-picker";

Color Picker Clear

Inherits button attributes.

Contains the following additional props:

Prop Type Default Toggle details
initial ColorPickerInitialPartProjection —
Description
Supplies the Astro server-render projection for this Color Picker part before browser initialization.
Classification
Wrapper prop
Type imports
Astro import type { ColorPickerInitialPartProjection } from "@starwind-ui/astro/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.3.0 7 releases

v2.3.0

  • Color Picker with formats and no format now starts on the first listed format in every framework. Before, Vue showed a blank format selector and Svelte added a HEX option.
  • In Svelte, a defined value or format that you pass when ColorPicker mounts now stays under your control, as in React and Vue. To change it, use bind: or update your state in the change callback. A form reset keeps it. If you pass undefined at mount, ColorPicker keeps its own state. A later defined value sets an initially undefined model without firing the change callback.
  • In Astro, an attribute that you set on ColorPickerInput now wins over the component’s own default for the same attribute, such as role or aria-label.

v2.2.0

  • Vue and Svelte keep app-controlled colors and formats under app control, including after form resets. Set controlled values when the picker mounts; remount it to change between controlled and uncontrolled use.
  • Vue Color Picker keeps the selected color when a value change is canceled.
  • Added step to channel sliders across frameworks to control how much each keyboard action changes the value.
  • Fixed Svelte Color Picker popup styling and clicks inside native dialogs.
  • Keep custom portal targets for Color Picker controls inside the picker root so input changes reach the picker.
  • Fixed React and Vue form resets overwriting a newer color or format selection. Canceling a reset keeps the current selection.
  • Fixed nested Svelte overlays inside a dialog appearing behind their parent or failing to receive clicks.
  • Fixed nested overlays appearing behind their parent in Vue and Svelte.
  • React Color Picker now avoids rebuilding its controls when only the selected color changes. It still connects controls that your app adds or replaces.

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

  • The default export in index.ts now has a name, ColorPickerParts, so framework tools show a clear name.
  • Fixed build errors in the Astro and React Color Picker when you pass swatches as plain color values or as objects with a label, in JavaScript and TypeScript.
  • In React, the format control now shows the set format, such as HEX, with the selected style before anyone uses it.

v2.0.1

  • Removed unused imports and variables from the Astro and React components. Builds that report unused code as an error now pass.

v2.0.0

  • The component classes now use the Tailwind CSS v4 short form for CSS variables. This is a cleanup of the source. The props and the look stay the same.
  • <ColorPicker /> with no children now renders a complete popup picker or inline editor.
  • Set the size on ColorPicker and on ColorPickerContent, which renders in a portal and has its own size. Both default to md. With the default parts, ColorPicker passes its size to its content.
  • Removed size from the inner parts. Move it to ColorPicker or ColorPickerContent. To size only the format popup, replace size on ColorPickerInput with formatContentSize.
  • Added props for the label, the format control, the format list, the EyeDropper button, the value text, clearing, and swatches. Alpha is still on by default.
  • Labels, control wrappers, area thumbs, sliders, format selectors, value inputs, and hidden form inputs are now part of the components that hold them.
  • Children that you pass now replace the default parts that show. To change the inner parts, use the Color Picker Primitive.

v0.1.0

  • Added Color Picker for Astro and React. It shows as a popup or inline, and it supports alpha, swatches, HEX, RGB, HSL, and HSB editing, and the native form. It gets its behavior from Starwind Runtime.