ColorPicker
ColorPicker captures theme colors, brand swatches, or user-selected color values.
@duskmoon-dev/components/color-pickerUsage
When to use
- Use it inside forms, filters, settings, and any workflow that captures user input.
- Prefer controlled props when the value must stay synchronized with application state.
Implementation notes
Features
Documents default values, value props, and change callbacks for form integration.
Surfaces status, size, disabled, and option data patterns where the component supports them.
ColorPicker is most often configured through `triggerProps`, `value`, `defaultValue`, `format`.
Renders value, size, format, and text
Feature Demos
Feature demos are authored for the component page, then supplemented with behavior scenarios from the component test coverage.
Basic usage
Import the component stylesheet and ColorPicker from its package subpath, then render it with the core props.
Source
import "@duskmoon-dev/components/styles.css";
import { ColorPicker } from "@duskmoon-dev/components/color-picker";
export function Example() {
return (<ColorPicker
defaultValue="#1677ff"
size="large"
format="hex"
showText
onChange={(value, css) => console.log(value, css)}
/>);
}Renders value, size, format, and text
test-backedColorPicker scenario from the component test coverage: renders value, size, format, and text.
Source
import "@duskmoon-dev/components/styles.css";
import { ColorPicker } from "@duskmoon-dev/components/color-picker";
export function ColorPickerRendersValueSizeFormatDemo() {
return (<ColorPicker
defaultValue="#1677ff"
size="large"
format="hex"
showText
onChange={(value, css) => console.log(value, css)}
/>);
}Supports uncontrolled open and input changes
test-backedColorPicker scenario from the component test coverage: supports uncontrolled open and input changes.
Source
import "@duskmoon-dev/components/styles.css";
import { ColorPicker } from "@duskmoon-dev/components/color-picker";
export function ColorPickerSupportsUncontrolledOpenAndDemo() {
return (<ColorPicker
defaultValue="#1677ff"
size="large"
format="hex"
showText
onChange={(value, css) => console.log(value, css)}
/>);
}Supports presets and showText render function
test-backedColorPicker scenario from the component test coverage: supports presets and showtext render function.
Source
import "@duskmoon-dev/components/styles.css";
import { ColorPicker } from "@duskmoon-dev/components/color-picker";
export function ColorPickerSupportsPresetsAndShowTextDemo() {
return (<ColorPicker
defaultValue="#1677ff"
size="large"
format="hex"
showText
onChange={(value, css) => console.log(value, css)}
/>);
}Supports format changes and hover trigger
test-backedColorPicker scenario from the component test coverage: supports format changes and hover trigger.
Source
import "@duskmoon-dev/components/styles.css";
import { ColorPicker } from "@duskmoon-dev/components/color-picker";
export function ColorPickerSupportsFormatChangesAndDemo() {
return (<ColorPicker
defaultValue="#1677ff"
size="large"
format="hex"
showText
onChange={(value, css) => console.log(value, css)}
/>);
}Respects disabled state
test-backedColorPicker scenario from the component test coverage: respects disabled state.
Source
import "@duskmoon-dev/components/styles.css";
import { ColorPicker } from "@duskmoon-dev/components/color-picker";
export function ColorPickerRespectsDisabledStateDemo() {
return (<ColorPicker
defaultValue="#1677ff"
size="large"
format="hex"
showText
onChange={(value, css) => console.log(value, css)}
/>);
}Has package stylesheet selectors for local color picker classes
test-backedColorPicker scenario from the component test coverage: has package stylesheet selectors for local color picker classes.
Source
import "@duskmoon-dev/components/styles.css";
import { ColorPicker } from "@duskmoon-dev/components/color-picker";
export function ColorPickerHasPackageStylesheetSelectorsDemo() {
return (<ColorPicker
defaultValue="#1677ff"
size="large"
format="hex"
showText
onChange={(value, css) => console.log(value, css)}
/>);
}Forwards native trigger labels and errors while retaining picker actions
test-backedColorPicker scenario from the component test coverage: forwards native trigger labels and errors while retaining picker actions.
Source
import "@duskmoon-dev/components/styles.css";
import { ColorPicker } from "@duskmoon-dev/components/color-picker";
export function ColorPickerForwardsNativeTriggerLabelsDemo() {
return (<ColorPicker
defaultValue="#1677ff"
size="large"
format="hex"
showText
onChange={(value, css) => console.log(value, css)}
/>);
}Selects saturation/brightness with a captured pointer and completes on release
test-backedColorPicker scenario from the component test coverage: selects saturation/brightness with a captured pointer and completes on release.
Source
import "@duskmoon-dev/components/styles.css";
import { ColorPicker } from "@duskmoon-dev/components/color-picker";
export function ColorPickerSelectsSaturationBrightnessWithDemo() {
return (<ColorPicker
defaultValue="#1677ff"
size="large"
format="hex"
showText
onChange={(value, css) => console.log(value, css)}
/>);
}Keyboard selection and hue update hex without changing the chosen format
test-backedColorPicker scenario from the component test coverage: keyboard selection and hue update hex without changing the chosen format.
Source
import "@duskmoon-dev/components/styles.css";
import { ColorPicker } from "@duskmoon-dev/components/color-picker";
export function ColorPickerKeyboardSelectionAndHueDemo() {
return (<ColorPicker
defaultValue="#1677ff"
size="large"
format="hex"
showText
onChange={(value, css) => console.log(value, css)}
/>);
}Disabled open panels block visual, input, and preset changes
test-backedColorPicker scenario from the component test coverage: disabled open panels block visual, input, and preset changes.
Source
import "@duskmoon-dev/components/styles.css";
import { ColorPicker } from "@duskmoon-dev/components/color-picker";
export function ColorPickerDisabledOpenPanelsBlockDemo() {
return (<ColorPicker
defaultValue="#1677ff"
size="large"
format="hex"
showText
onChange={(value, css) => console.log(value, css)}
/>);
}Invalid hex text stays editable until a graphical selection corrects it
test-backedColorPicker scenario from the component test coverage: invalid hex text stays editable until a graphical selection corrects it.
Source
import "@duskmoon-dev/components/styles.css";
import { ColorPicker } from "@duskmoon-dev/components/color-picker";
export function ColorPickerInvalidHexTextStaysDemo() {
return (<ColorPicker
defaultValue="#1677ff"
size="large"
format="hex"
showText
onChange={(value, css) => console.log(value, css)}
/>);
}Clamps touch/pointer selection outside the plane and ignores unrelated pointer movement
test-backedColorPicker scenario from the component test coverage: clamps touch/pointer selection outside the plane and ignores unrelated pointer movement.
Source
import "@duskmoon-dev/components/styles.css";
import { ColorPicker } from "@duskmoon-dev/components/color-picker";
export function ColorPickerClampsTouchPointerSelectionDemo() {
return (<ColorPicker
defaultValue="#1677ff"
size="large"
format="hex"
showText
onChange={(value, css) => console.log(value, css)}
/>);
}Escape returns focus to the labeled trigger and outside pointer closes without losing value
test-backedColorPicker scenario from the component test coverage: escape returns focus to the labeled trigger and outside pointer closes without losing value.
Source
import "@duskmoon-dev/components/styles.css";
import { ColorPicker } from "@duskmoon-dev/components/color-picker";
export function ColorPickerEscapeReturnsFocusToDemo() {
return (<ColorPicker
defaultValue="#1677ff"
size="large"
format="hex"
showText
onChange={(value, css) => console.log(value, css)}
/>);
}Controlled open remains visible on dismissal until the owner updates
test-backedColorPicker scenario from the component test coverage: controlled open remains visible on dismissal until the owner updates.
Source
import "@duskmoon-dev/components/styles.css";
import { ColorPicker } from "@duskmoon-dev/components/color-picker";
export function ColorPickerControlledOpenRemainsVisibleDemo() {
return (<ColorPicker
defaultValue="#1677ff"
size="large"
format="hex"
showText
onChange={(value, css) => console.log(value, css)}
/>);
}Theme aware
Docs previews inherit the DuskMoon data-theme value. Use the header switch to compare light and dark rendering.
Source
<div data-theme="sunshine">
<ColorPicker
defaultValue="#1677ff"
size="large"
format="hex"
showText
onChange={(value, css) => console.log(value, css)}
/>
</div>
<div data-theme="moonlight">
<ColorPicker
defaultValue="#1677ff"
size="large"
format="hex"
showText
onChange={(value, css) => console.log(value, css)}
/>
</div>API
The API reference below lists every parsed exported type or interface for ColorPicker. Start with `triggerProps`, `value`, `defaultValue`, `format` for common usage.
packages/components/src/components/color-picker/ColorPicker.types.tsScenarios: packages/components/src/components/color-picker/ColorPicker.test.tsx| Prop | Type | Required | Description |
|---|---|---|---|
triggerProps | ComponentProps<"button"> | No | triggerProps configures ColorPicker. |
value | ColorValue | No | value configures ColorPicker. |
defaultValue | ColorValue | No | defaultValue configures ColorPicker. |
format | ColorPickerFormat | No | format configures ColorPicker. |
presets | ColorPreset[] | No | presets configures ColorPicker. |
trigger | ColorPickerTrigger | No | trigger configures ColorPicker. |
open | boolean | No | open configures ColorPicker. |
defaultOpen | boolean | No | defaultOpen configures ColorPicker. |
disabled | boolean | No | disabled configures ColorPicker. |
showText | boolean | ((color: string) => ReactNode) | No | showText configures ColorPicker. |
size | ColorPickerSize | No | size configures ColorPicker. |
panelRender | (panel: ReactNode) => ReactNode | No | panelRender configures ColorPicker. |
onChange | (value: ColorValue, css: string) => void | No | onChange configures ColorPicker. |
onChangeComplete | (value: ColorValue, css: string) => void | No | onChangeComplete configures ColorPicker. |
onFormatChange | (format: ColorPickerFormat) => void | No | onFormatChange configures ColorPicker. |
onOpenChange | (open: boolean) => void | No | onOpenChange configures ColorPicker. |
| Prop | Type | Required | Description |
|---|---|---|---|
r | number | Yes | r configures ColorPicker. |
g | number | Yes | g configures ColorPicker. |
b | number | Yes | b configures ColorPicker. |
a | number | No | a configures ColorPicker. |
| Prop | Type | Required | Description |
|---|---|---|---|
h | number | Yes | h configures ColorPicker. |
s | number | Yes | s configures ColorPicker. |
b | number | Yes | b configures ColorPicker. |
a | number | No | a configures ColorPicker. |
| Prop | Type | Required | Description |
|---|---|---|---|
label | ReactNode | No | label configures ColorPicker. |
colors | ColorValue[] | Yes | colors configures ColorPicker. |
Type definition
"hex" | "rgb" | "hsb"Type definition
"hover" | "click"Type definition
"small" | "middle" | "large" | "sm" | "md" | "lg"Type definition
string | RGBColor | HSBColorType definition
ForwardRefExoticComponent< ColorPickerProps & RefAttributes<HTMLDivElement> >