Color Picker

Color Picker lets users choose and submit short hexadecimal color values through a visual control.

Purpose

Color Picker lets users choose and submit short hexadecimal color values through a visual control.

Controlled color

"use client";

import { useState } from "react";
import { ColorPicker } from "@/components/ui/color-picker";

export function Example() {
  const [color, setColor] = useState("#232E4A");
  return <ColorPicker value={color} onValueChange={setColor} />;
}

Installation

With the Siteplane registry alias configured, add the component and import the installed source from your app.

CLI

pnpm dlx shadcn@4.16.1 add @siteplane/color-picker

Import

import { ColorPicker } from "@/components/ui/color-picker";

Need the machine-readable source metadata? View registry JSON.

Usage

Use Color Picker for direct color input such as brand or accent settings. Normal text values should stay on Input.

"use client";

import { useState } from "react";
import { ColorPicker } from "@/components/ui/color-picker";

export function Example() {
  const [color, setColor] = useState("#232E4A");
  return <ColorPicker value={color} onValueChange={setColor} />;
}

Examples

Swatch-only triggers, sizes, states and form wiring are props of the same primitive.

Default

Uncontrolled with a defaultValue; name makes the value available to forms.

<ColorPicker
  aria-label="Success color"
  defaultValue="#22c55e"
  name="success-color"
/>

Swatch only

showValue={false} hides the hex text for compact toolbars. Keep an aria-label on the trigger.

<ColorPicker
  aria-label="Choose warning color"
  defaultValue="#f59e0b"
  showValue={false}
/>

Sizes

<ColorPicker size="sm" ... />
<ColorPicker ... />
<ColorPicker size="lg" ... />
<ColorPicker size="xl" ... />

Disabled

<ColorPicker
  aria-label="Locked color"
  defaultValue="#64748b"
  disabled
/>

Field integration

Accent color

The hex value is normalized and can be copied from the popup.

<Field>
  <FieldLabel>Accent color</FieldLabel>
  <ColorPicker defaultValue="#8b5cf6" name="accent" />
  <FieldDescription>
    The hex value is normalized and can be copied from the popup.
  </FieldDescription>
</Field>

Form integration

<Form onSubmit={onSubmit}>
  <Field>
    <FieldLabel>Brand color</FieldLabel>
    <ColorPicker defaultValue="#14b8a6" name="brand-color" required />
    <FieldDescription>
      A hidden input submits the hex value with the form.
    </FieldDescription>
  </Field>
  <Button loading={loading} type="submit">Submit</Button>
</Form>

// onSubmit
const formData = new FormData(event.currentTarget);
const submittedColor = String(formData.get("brand-color") ?? "");

API Reference

The reference lists the source-owned exports and props that are easy to miss in visual examples. Inherited Base UI props remain available unless the wrapper narrows them.

The submitted form value is a normalized hexadecimal string.
name, form, required, and disabled are mirrored through the built-in hidden form field.
size accepts "sm", "default", "lg", and "xl" and otherwise inherits SiteplaneUIProvider controlSize.
Use the swatch-only form only when visible label or surrounding context names the control.

Motion

Component motion uses the shared Siteplane motion contract. See the global motion guide for provider setup, tokens and reduced-motion behavior.

The picker popup follows the native Popover motion contract.
Hue and swatch controls keep native pointer and focus behavior.
Copy feedback uses the shared icon feedback sequence and respects reduced motion.

Accessibility

Give the trigger and every text field an accessible name.
Keep visible focus throughout the trigger, popup, and text fields.
Preserve hidden-field semantics for name, form, required, and disabled.
Do not use a native browser color input as a parallel visible control.

Implementation Guidance

Keep hexadecimal value as the public form contract.
Use Color Picker rather than a raw visible color input.
Preserve normalization, form participation, popup, and focus behavior.