Swatch trigger with hex trailing, hover border, and channel editors.
Also known as: colour picker, swatch picker, hex picker, color swatch
Install with the CLI, or copy the component source into your project.
Add color-picker (npm)
1npx --yes -p @default-file/ui df-ui add color-picker
Pill trigger shows the hex value. The whole pill opens the picker.
Replace the hex with an X. The pill still opens the picker; X fires onClear.
Inherits the theme hover border on pill triggers. Override with hoverBorderColor, or set hoverBorder false.
Pill swatch trigger with optional hex or clear trailing, hover border controls, and channel editors in a popover.
| Prop | Type | Default | Notes |
|---|---|---|---|
| value | string | - | Current color as a hex string (required). |
| onChange | (hex: string) => void | - | Called when the color changes (required). |
| label | string | "Pick color" | Accessible name for the swatch trigger. |
| trailing | "hex" | "clear" | - | Optional trailing control: show hex text, or a clear action. Pill triggers use the hover border contract. |
| onClear | () => void | - | Required when trailing is "clear". |
| clearLabel | string | "Remove color" | Accessible label for the clear control. |
| hoverBorder | boolean | - | Instance hover border on pill triggers (hex or clear). Omit to inherit the theme. Set false to keep the resting border. Set true to force the hover border on. Dot only triggers do not use this contract. |
| hoverBorderColor | string | - | Hover border color when hover is active. Prefer tokens such as var(--foreground). Sets --df-color-picker-hover-border. |
| className | string | - | Additional styles on the pill trigger or swatch root. |
DOM structure markers for styling and tests. These are not component props. data-df="color-picker-trigger": Pill shell for trailing hex or clear. Owns layout, start padding, resting border, and hover border chrome. data-trailing: hex or clear on the pill trigger. data-df="color-picker-open": Inner swatch control on the clear pill. data-hover-border: true or false when hoverBorder is set; omit to inherit the host theme.
Popover editors (internal UI): Opened panel supports hex, rgb, hsl, and hsb channel modes (not separate props). Placement flips when there is not enough space.
Theme defaults live on :root. Override these globally or on a local host.
| Token | Type | Default | Notes |
|---|---|---|---|
| --df-color-picker-width | CSS length | 300px | Popover panel width. |
| --df-color-picker-height | CSS length | 220px | Popover panel height. |
| --df-color-picker-hex-width | CSS length | 7ch | Fixed width for the hex label on the pill trigger so it does not reflow while dragging. |
| --df-color-picker-trigger-height | CSS length | calc(8 * var(--spacing-unit)) | Pill trigger height. |
| --df-color-picker-trigger-pad-start | CSS length | calc(1.5 * var(--spacing-unit)) | Inset from the start edge of the pill to the swatch. |
| --df-color-picker-trigger-pad-end | CSS length | calc(2.5 * var(--spacing-unit)) | Inset from the end edge of the hex pill. |
| --df-color-picker-trigger-gap | CSS length | calc(1.5 * var(--spacing-unit)) | Space between the swatch and the hex label. |
| --df-color-picker-trigger-pad-end-clear | CSS length | calc(0.5 * var(--spacing-unit)) | Inset from the end edge of the clear pill. |
| --df-color-picker-trigger-gap-clear | CSS length | calc(1 * var(--spacing-unit)) | Space between the swatch and the clear control. |
| --df-color-picker-border | CSS color | var(--input) | Resting border on the pill trigger. |
| --df-hover-border | CSS keyword | on | Theme field hover border. on paints the ink hover border; off keeps the resting border. Runtime gating uses data-df-hover-border on html. Set with df-ui init --hover-border. Default on. |
| --df-color-picker-hover-border | CSS color | var(--foreground) | Hover border when the theme or instance enables hover. Defaults to the ink foreground. Override with hoverBorderColor. |
| --df-color-picker-bg | CSS color | var(--muted) | Pill trigger fill. |
| --df-shadow-picker-thumb | CSS shadow | 0 0 0 1px rgb(0 0 0 / 0.45) | Ring around the channel thumb. |
| --df-corner-shape | CSS corner-shape | var(--df-corner-shape-round) | Theme corner curve for all kit chrome. round = circular arcs; smooth = continuous squircle. Set with df-ui init --corner-shape, or override on :root. Default round. |