Color Picker
---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}/>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" },];
export function Example() { return ( <ColorPicker label="Brand color" name="brand-color" defaultValue="#ff000080" alpha swatches={swatches} /> );}<script setup lang="ts">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" },];</script>
<template> <ColorPicker label="Brand color" name="brand-color" defaultValue="#ff000080" alpha :swatches="swatches" /></template><script lang="ts"> 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" }, ];</script>
<ColorPicker label="Brand color" name="brand-color" defaultValue="#ff000080" alpha {swatches}/>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
pnpx starwind@latest add color-picker --framework astronpx starwind@latest add color-picker --framework astroyarn dlx starwind@latest add color-picker --framework astropnpx starwind@latest add color-picker --framework reactnpx starwind@latest add color-picker --framework reactyarn dlx starwind@latest add color-picker --framework reactpnpx starwind@latest add color-picker --framework vuenpx starwind@latest add color-picker --framework vueyarn dlx starwind@latest add color-picker --framework vuepnpx starwind@latest add color-picker --framework sveltenpx starwind@latest add color-picker --framework svelteyarn dlx starwind@latest add color-picker --framework svelteTo 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}/>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" },];
export function Example() { return ( <ColorPicker label="Brand color" name="brand-color" defaultValue="#ff000080" alpha swatches={swatches} /> );}<script setup lang="ts">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" },];</script>
<template> <ColorPicker label="Brand color" name="brand-color" defaultValue="#ff000080" alpha :swatches="swatches" /></template><script lang="ts"> 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" }, ];</script>
<ColorPicker label="Brand color" name="brand-color" defaultValue="#ff000080" alpha {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
Large
Independent popup size
---import { ColorPicker, ColorPickerContent, ColorPickerTrigger,} from "@/components/starwind/color-picker";---
<div class="space-y-10"> <section class="mx-auto max-w-md space-y-3"> <h3 class="text-sm font-medium">Small</h3> <ColorPicker size="sm" label="Compact brand color" defaultValue="#ef4444" /> </section>
<section class="mx-auto max-w-md space-y-3"> <h3 class="text-sm font-medium">Large</h3> <ColorPicker size="lg" label="Large accent color" defaultValue="#0ea5e9" /> </section>
<section class="mx-auto max-w-md space-y-3"> <h3 class="text-sm font-medium">Independent popup size</h3> <ColorPicker size="sm" defaultValue="#8b5cf6"> <ColorPickerTrigger>Compact trigger</ColorPickerTrigger> <ColorPickerContent size="lg" aria-label="Large color editor" /> </ColorPicker> </section></div>import { ColorPicker, ColorPickerContent, ColorPickerTrigger,} from "@/components/starwind/color-picker";
export function Example() { return ( <div className="space-y-10"> <section className="mx-auto max-w-md space-y-3"> <h3 className="text-sm font-medium">Small</h3> <ColorPicker size="sm" label="Compact brand color" defaultValue="#ef4444" /> </section>
<section className="mx-auto max-w-md space-y-3"> <h3 className="text-sm font-medium">Large</h3> <ColorPicker size="lg" label="Large accent color" defaultValue="#0ea5e9" /> </section>
<section className="mx-auto max-w-md space-y-3"> <h3 className="text-sm font-medium">Independent popup size</h3> <ColorPicker size="sm" defaultValue="#8b5cf6"> <ColorPickerTrigger>Compact trigger</ColorPickerTrigger> <ColorPickerContent size="lg" aria-label="Large color editor" /> </ColorPicker> </section> </div> );}<script setup lang="ts">import { ColorPicker, ColorPickerContent, ColorPickerTrigger,} from "@/components/starwind/color-picker";</script>
<template> <div class="space-y-10"> <section class="mx-auto max-w-md space-y-3"> <h3 class="text-sm font-medium">Small</h3> <ColorPicker size="sm" label="Compact brand color" defaultValue="#ef4444" /> </section>
<section class="mx-auto max-w-md space-y-3"> <h3 class="text-sm font-medium">Large</h3> <ColorPicker size="lg" label="Large accent color" defaultValue="#0ea5e9" /> </section>
<section class="mx-auto max-w-md space-y-3"> <h3 class="text-sm font-medium">Independent popup size</h3> <ColorPicker size="sm" defaultValue="#8b5cf6"> <ColorPickerTrigger>Compact trigger</ColorPickerTrigger> <ColorPickerContent size="lg" aria-label="Large color editor" /> </ColorPicker> </section> </div></template><script lang="ts"> import { ColorPicker, ColorPickerContent, ColorPickerTrigger, } from "@/components/starwind/color-picker";</script>
<div class="space-y-10"> <section class="mx-auto max-w-md space-y-3"> <h3 class="text-sm font-medium">Small</h3> <ColorPicker size="sm" label="Compact brand color" defaultValue="#ef4444" /> </section> <section class="mx-auto max-w-md space-y-3"> <h3 class="text-sm font-medium">Large</h3> <ColorPicker size="lg" label="Large accent color" defaultValue="#0ea5e9" /> </section> <section class="mx-auto max-w-md space-y-3"> <h3 class="text-sm font-medium">Independent popup size</h3> <ColorPicker size="sm" defaultValue="#8b5cf6"> <ColorPickerTrigger>Compact trigger</ColorPickerTrigger> <ColorPickerContent size="lg" aria-label="Large color editor" /> </ColorPicker> </section></div>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.
---import type { ColorPickerValueChangeDetails } from "@starwind-ui/astro/color-picker";import { ColorPicker } from "@/components/starwind/color-picker";
const swatches = [ { value: "#10b981", label: "Emerald" }, { value: "#0ea5e9", label: "Sky" }, { value: "#8b5cf6", label: "Violet" },];---
<div class="grid gap-5 rounded-lg border p-5 sm:grid-cols-[8rem_1fr]"> <div class="aspect-square rounded-md border shadow-sm" style="background-color: #4f46e5" data-color-preview aria-hidden="true" /> <div class="space-y-3"> <ColorPicker inline id="preview-color" label="Preview color" defaultValue="#4f46e5" alpha={false} formatControl="native" showEyeDropper={false} swatches={swatches} /> <output class="text-muted-foreground block text-sm tabular-nums" data-color-value> #4f46e5 </output> </div></div>
<script> const root = document.querySelector("#preview-color"); const preview = document.querySelector<HTMLElement>("[data-color-preview]"); const value = document.querySelector<HTMLOutputElement>("[data-color-value]");
root?.addEventListener("starwind:value-change", (event) => { const { valueAsString } = (event as CustomEvent<ColorPickerValueChangeDetails>).detail; if (preview) preview.style.backgroundColor = valueAsString; if (value) value.value = valueAsString; });</script>import { parseColor, type ColorPickerColor, type ColorPickerFormat,} from "@starwind-ui/react/color-picker";import { useState } from "react";import { ColorPicker } from "@/components/starwind/color-picker";
export function Example() { const [value, setValue] = useState<ColorPickerColor | null>(parseColor("#4f46e5")); const [format, setFormat] = useState<ColorPickerFormat>("hex"); const color = value?.toString("hex") ?? "transparent";
return ( <div className="grid gap-5 rounded-lg border p-5 sm:grid-cols-[8rem_1fr]"> <div className="aspect-square rounded-md border shadow-sm" style={{ backgroundColor: color }} aria-hidden="true" /> <div className="space-y-3"> <ColorPicker inline label="Preview color" value={value} onValueChange={setValue} format={format} onFormatChange={setFormat} alpha={false} formatControl="native" showEyeDropper={false} swatches={[ { value: "#10b981", label: "Emerald" }, { value: "#0ea5e9", label: "Sky" }, { value: "#8b5cf6", label: "Violet" }, ]} /> <output className="text-muted-foreground block text-sm tabular-nums"> {color} </output> </div> </div> );}<script setup lang="ts">import type { ColorPickerValueChangeDetails } from "@starwind-ui/vue/color-picker";import { ColorPicker } from "@/components/starwind/color-picker";import { ref } from "vue";
const swatches = [ { value: "#10b981", label: "Emerald" }, { value: "#0ea5e9", label: "Sky" }, { value: "#8b5cf6", label: "Violet" },];
const color = ref("#4f46e5");function updateColor(_value: unknown, detail: ColorPickerValueChangeDetails) { color.value = detail.valueAsString;}</script>
<template> <div class="grid gap-5 rounded-lg border p-5 sm:grid-cols-[8rem_1fr]"> <div class="aspect-square rounded-md border shadow-sm" :style="{ backgroundColor: color }" data-color-preview aria-hidden="true" /> <div class="space-y-3"> <ColorPicker inline id="preview-color" label="Preview color" defaultValue="#4f46e5" @value-change="updateColor" :alpha="false" formatControl="native" :showEyeDropper="false" :swatches="swatches" /> <output class="text-muted-foreground block text-sm tabular-nums" data-color-value> {{ color }} </output> </div> </div></template><script lang="ts"> import type { ColorPickerValueChangeDetails } from "@starwind-ui/svelte/color-picker"; import { ColorPicker } from "@/components/starwind/color-picker";
const swatches = [ { value: "#10b981", label: "Emerald" }, { value: "#0ea5e9", label: "Sky" }, { value: "#8b5cf6", label: "Violet" }, ];
let color = $state("#4f46e5"); function updateColor(_value: unknown, detail: ColorPickerValueChangeDetails) { color = detail.valueAsString; }</script>
<div class="grid gap-5 rounded-lg border p-5 sm:grid-cols-[8rem_1fr]"> <div class="aspect-square rounded-md border shadow-sm" style:background-color={color} data-color-preview aria-hidden="true" ></div> <div class="space-y-3"> <ColorPicker inline id="preview-color" label="Preview color" defaultValue="#4f46e5" onValueChange={updateColor} alpha={false} formatControl="native" showEyeDropper={false} {swatches} /> <output class="text-muted-foreground block text-sm tabular-nums" data-color-value> {color} </output> </div></div>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.
---import { ColorPicker } from "@/components/starwind/color-picker";---
<section class="space-y-4 rounded-lg border p-5"> <div> <h3 class="font-medium">Theme accent</h3> <p class="text-muted-foreground text-sm"> Used for links, focus rings, and primary actions. </p> </div> <ColorPicker inline label="Accent color" defaultValue="#7c3aed" alpha={false} showEyeDropper={false} swatches={[ { value: "#10b981", label: "Emerald" }, { value: "#0ea5e9", label: "Sky" }, { value: "#8b5cf6", label: "Violet" }, ]} /></section>import { ColorPicker } from "@/components/starwind/color-picker";
export function Example() { return ( <section className="space-y-4 rounded-lg border p-5"> <div> <h3 className="font-medium">Theme accent</h3> <p className="text-muted-foreground text-sm"> Used for links, focus rings, and primary actions. </p> </div> <ColorPicker inline label="Accent color" defaultValue="#7c3aed" alpha={false} showEyeDropper={false} swatches={[ { value: "#10b981", label: "Emerald" }, { value: "#0ea5e9", label: "Sky" }, { value: "#8b5cf6", label: "Violet" }, ]} /> </section> );}<script setup lang="ts">import { ColorPicker } from "@/components/starwind/color-picker";</script>
<template> <section class="space-y-4 rounded-lg border p-5"> <div> <h3 class="font-medium">Theme accent</h3> <p class="text-muted-foreground text-sm">Used for links, focus rings, and primary actions.</p> </div> <ColorPicker inline label="Accent color" defaultValue="#7c3aed" :alpha="false" :showEyeDropper="false" :swatches="[ { value: '#10b981', label: 'Emerald' }, { value: '#0ea5e9', label: 'Sky' }, { value: '#8b5cf6', label: 'Violet' }, ]" /> </section></template><script lang="ts"> import { ColorPicker } from "@/components/starwind/color-picker";</script>
<section class="space-y-4 rounded-lg border p-5"> <div> <h3 class="font-medium">Theme accent</h3> <p class="text-muted-foreground text-sm"> Used for links, focus rings, and primary actions. </p> </div> <ColorPicker inline label="Accent color" defaultValue="#7c3aed" alpha={false} showEyeDropper={false} swatches={[ { value: "#10b981", label: "Emerald" }, { value: "#0ea5e9", label: "Sky" }, { value: "#8b5cf6", label: "Violet" }, ]} /></section>Format Controls and Optional Features
formataccepts"hex","rgb","hsl", or"hsb"and defaults to"hex". When you passformatswithoutformat, 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.formatslimits the available formats. Duplicate entries are removed, and the active format remains available even if it was omitted from the array.alphadefaults totrue. Setalpha={false}when transparency is not valid.showEyeDropperdefaults totrue. 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.clearableallows an empty value and adds the default Clear action. It replaces the old styledallowEmptyandshowClearcombination.swatchesaccepts 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/>import { ColorPicker } from "@/components/starwind/color-picker";
export function Example() { return ( <ColorPicker label="Accent color" defaultValue="rgb(37, 99, 235)" formats={["rgb", "hex"]} formatControl="native" alpha={false} showEyeDropper={false} clearable /> );}<script setup lang="ts">import { ColorPicker } from "@/components/starwind/color-picker";</script>
<template> <ColorPicker label="Accent color" defaultValue="rgb(37, 99, 235)" :formats="['rgb', 'hex']" formatControl="native" :alpha="false" :showEyeDropper="false" clearable /></template><script lang="ts"> import { ColorPicker } from "@/components/starwind/color-picker";</script>
<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.
---import { Button } from "@/components/starwind/button";import { ColorPicker } from "@/components/starwind/color-picker";
const swatches = [ { value: "#10b981", label: "Emerald" }, { value: "#0ea5e9", label: "Sky" }, { value: "#8b5cf6", label: "Violet" },];---
<form class="space-y-5" data-color-picker-form> <ColorPicker label="Accent color" name="accent" defaultValue="#2563eb" required swatches={swatches} />
<div class="flex flex-wrap items-center gap-3"> <Button type="submit">Save settings</Button> <Button type="reset" variant="outline">Reset</Button> <output class="text-muted-foreground text-sm" aria-live="polite"> Not submitted </output> </div></form>
<script> const form = document.querySelector<HTMLFormElement>("[data-color-picker-form]"); const result = form?.querySelector<HTMLOutputElement>("output");
form?.addEventListener("submit", (event) => { event.preventDefault(); if (!form.reportValidity()) return; if (result) { result.value = `Saved accent: ${String(new FormData(form).get("accent") ?? "")}`; } }); form?.addEventListener("reset", () => { window.setTimeout(() => { if (result) result.value = "Reset to default"; }, 0); });</script>import { useState } from "react";import { Button } from "@/components/starwind/button";import { ColorPicker } from "@/components/starwind/color-picker";
export function Example() { const [result, setResult] = useState("Not submitted");
return ( <form className="space-y-5" onSubmit={(event) => { event.preventDefault(); if (!event.currentTarget.reportValidity()) return; const value = new FormData(event.currentTarget).get("accent"); setResult(`Saved accent: ${String(value ?? "")}`); }} onReset={() => setResult("Reset to default")} > <ColorPicker label="Accent color" name="accent" defaultValue="#2563eb" required swatches={[ { value: "#10b981", label: "Emerald" }, { value: "#0ea5e9", label: "Sky" }, { value: "#8b5cf6", label: "Violet" }, ]} />
<div className="flex flex-wrap items-center gap-3"> <Button type="submit">Save settings</Button> <Button type="reset" variant="outline">Reset</Button> <output className="text-muted-foreground text-sm" aria-live="polite"> {result} </output> </div> </form> );}<script setup lang="ts">import { Button } from "@/components/starwind/button";import { ColorPicker } from "@/components/starwind/color-picker";import { ref } from "vue";
const swatches = [ { value: "#10b981", label: "Emerald" }, { value: "#0ea5e9", label: "Sky" }, { value: "#8b5cf6", label: "Violet" },];
const result = ref("Not submitted");function submit(event: Event) { const form = event.currentTarget as HTMLFormElement; if (form.reportValidity()) result.value = `Saved accent: ${String(new FormData(form).get("accent") ?? "")}`;}</script>
<template> <form @submit.prevent="submit" @reset="result = 'Reset to default'" class="space-y-5" data-color-picker-form > <ColorPicker label="Accent color" name="accent" defaultValue="#2563eb" required :swatches="swatches" />
<div class="flex flex-wrap items-center gap-3"> <Button type="submit">Save settings</Button> <Button type="reset" variant="outline">Reset</Button> <output class="text-muted-foreground text-sm" aria-live="polite"> {{ result }} </output> </div> </form></template><script lang="ts"> import { Button } from "@/components/starwind/button"; import { ColorPicker } from "@/components/starwind/color-picker";
const swatches = [ { value: "#10b981", label: "Emerald" }, { value: "#0ea5e9", label: "Sky" }, { value: "#8b5cf6", label: "Violet" }, ];
let result = $state("Not submitted"); function submit(event: Event) { const form = event.currentTarget as HTMLFormElement; if (form.reportValidity()) result = `Saved accent: ${String(new FormData(form).get("accent") ?? "")}`; }</script>
<form onsubmit={(event) => { event.preventDefault(); submit(event); }} onreset={() => { result = "Reset to default"; }} class="space-y-5" data-color-picker-form> <ColorPicker label="Accent color" name="accent" defaultValue="#2563eb" required {swatches} /> <div class="flex flex-wrap items-center gap-3"> <Button type="submit">Save settings</Button> <Button type="reset" variant="outline">Reset</Button> <output class="text-muted-foreground text-sm" aria-live="polite">{result}</output> </div></form>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>import { ColorPicker, ColorPickerContent, ColorPickerTrigger,} from "@/components/starwind/color-picker";
export function Example() { return ( <ColorPicker label="Brand color" defaultValue="#0ea5e9"> <span className="text-sm font-medium" data-slot="color-picker-label"> Brand color </span> <ColorPickerTrigger showValueText={false} aria-label="Open brand color picker" /> <ColorPickerContent aria-label="Brand color editor" /> </ColorPicker> );}<script setup lang="ts">import { ColorPicker, ColorPickerContent, ColorPickerTrigger,} from "@/components/starwind/color-picker";</script>
<template> <ColorPicker label="Brand color" defaultValue="#0ea5e9"> <span class="text-sm font-medium" data-slot="color-picker-label">Brand color</span> <ColorPickerTrigger :showValueText="false" aria-label="Open brand color picker" /> <ColorPickerContent aria-label="Brand color editor" /> </ColorPicker></template><script lang="ts"> import { ColorPicker, ColorPickerContent, ColorPickerTrigger, } from "@/components/starwind/color-picker";</script>
<ColorPicker label="Brand color" defaultValue="#0ea5e9"> <span class="text-sm font-medium" data-slot="color-picker-label">Brand color</span> <ColorPickerTrigger showValueText={false} aria-label="Open brand color picker" /> <ColorPickerContent 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 API | Replacement |
|---|---|
ColorPickerRoot | <ColorPicker inline> |
ColorPickerLabel | The label prop or an authored label |
ColorPickerControl | The default wrapper or an authored container |
ColorPickerAreaThumb | Included by ColorPickerArea |
ColorPickerSliders | The default editor or explicit channel sliders |
ColorPickerValueInput | <ColorPickerInput formatControl="none" /> |
| Native or styled format-select parts | ColorPickerInput or the root formatControl prop |
ColorPickerHiddenInput | Automatically rendered by ColorPicker |
allowEmpty plus showClear | clearable |
| Content swatch slot or React node | The root or content swatches array |
Inner anatomy size props | Set size on ColorPicker or ColorPickerContent |
ColorPickerInput size | ColorPickerInput formatContentSize for its nested Select popup |
Accessibility
- Use
labelfor 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, andreadOnlyaccording 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:
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";Reactimport 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";Reactimport 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";Reactimport 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";Reactimport 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";Reactimport type { ColorPickerValue } from "@starwind-ui/react/color-picker";
Color Picker Input
Inherits div attributes.
Contains the following additional props:
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";Reactimport 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:
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:
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";Reactimport 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";Reactimport type { ColorPickerValue } from "@starwind-ui/react/color-picker";
Color Picker Area
Inherits div attributes.
Contains the following additional props:
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:
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";Reactimport 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:
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";Reactimport 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:
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:
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:
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";Reactimport type { ColorPickerValue } from "@starwind-ui/react/color-picker";
Color Picker Eye Dropper
Inherits button attributes.
Contains the following additional props:
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:
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.
Primitive API
Runtime API
- Color Picker primitive
createColorPickerfrom@starwind-ui/runtime/color-picker
Changelog
View version history v2.3.0 7 releases
v2.3.0
- Color Picker with
formatsand noformatnow 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
valueorformatthat you pass when ColorPicker mounts now stays under your control, as in React and Vue. To change it, usebind:or update your state in the change callback. A form reset keeps it. If you passundefinedat mount, ColorPicker keeps its own state. A later defined value sets an initiallyundefinedmodel without firing the change callback. - In Astro, an attribute that you set on
ColorPickerInputnow wins over the component’s own default for the same attribute, such asroleoraria-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
stepto 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
portalContaineranddisablePortalto 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.tsnow 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
ColorPickerand onColorPickerContent, which renders in a portal and has its own size. Both default tomd. With the default parts,ColorPickerpasses its size to its content. - Removed
sizefrom the inner parts. Move it toColorPickerorColorPickerContent. To size only the format popup, replacesizeonColorPickerInputwithformatContentSize. - 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.