ColorPicker
A color area, a hue track and a hex code for picking any color, with optional presets.
import { ColorPicker } from "@butteryui/react";Demo
When to use it
Use it for
- Picking any color inline, such as in a panel that stays open
- Building your own color control; ColorDot opens one in a popover
Not for
- A color in a row of controls: use ColorDot, which opens this in a popover
- Choosing from a fixed set: use SwatchGrid
Examples
Background color
A slide's background color kept in state as #rrggbb; Reset beside it puts the first color back, and the thumbs glide there.
#7c9cf5
Fill with presets
A shape's fill with six presets and an undo, which keeps one step per drag, key, code or preset rather than per frame.
0 steps to undo
Locked fill
A picker that's disabled while its shape is locked, with the switch that unlocks it.
Unlock the shape to change its fill
Shape fill
A picker that keeps its own color and reports the one each drag, key or typed code settles on.
Picked #f5d06f
Variants and states
Any color
Drag in the area for saturation and brightness, along the track for hue, or type a code. Thumbs follow the pointer in the same frame.
#7c9cf5
With presets
Disabled
Props
ColorPicker
| Prop | Type | Default | Description |
|---|---|---|---|
labelrequired | string | What the color is for, such as "Background hue". It names the picker. | |
value | string | The color, as #rrggbb. Pair with onValueChange to control it. | |
defaultValue | string | The color at first when uncontrolled, as #rrggbb. Defaults to black. | |
onValueChange | ((value: string) => void) | Called with each change, as #rrggbb: every frame of a drag, each key press, each code or preset. | |
onValueCommit | ((value: string) => void) | Called when a drag ends, or a key, a typed code or a preset changes the color, with the color it settled on. | |
presets | readonly string[] | Colors to pick in one press, as #rrggbb, shown in rows of six under the code. | |
disabled | boolean | Keeps it from changing. | |
labels | Partial<ColorPickerLabels> | Words to use instead of the English ones. |
It also takes Omit<ComponentPropsWithRef<"div">, "defaultValue" | "onChange" | "children">.
ColorPickerLabels
The words a `ColorPicker` reads out, for other languages.
| Field | Type | Default | Description |
|---|---|---|---|
saturationrequired | string | Names the area's left-and-right control. | |
brightnessrequired | string | Names the area's up-and-down control. | |
huerequired | string | Names the hue track. | |
coderequired | string | Names the hex code field. | |
presetsrequired | string | Names the presets. | |
hintrequired | string | Says how to use the area with the keyboard. |
Accessibility
A group named by label holding three sliders, "Saturation" and "Brightness" for the area and "Hue" for the track, reading values such as "40%" and "210°", and a "Hex code" field. The area's two sliders share one Tab stop: left and right set the saturation, up and down the brightness, and focus moves to the slider changed so its value is read. Shift takes bigger steps, Page Up and Page Down ten steps, Home and End go to the ends. The code field edits a draft: Enter or leaving takes a valid code, Escape puts it back. Presets are a radio group.
| Keys | What they do |
|---|---|
| ArrowLeft or ArrowRight | Sets the saturation 1% at a time in the area, or turns the hue 1° on the hue track |
| ArrowUp or ArrowDown | Sets the brightness 1% at a time in the area, or turns the hue 1° on the hue track |
| Shift with an arrow key | Takes a step ten times as big |
| Page Up or Page Down | Takes ten steps at once |
| Home or End | Goes to the start or the end of the slider with focus |
| Enter | Takes the code typed in the hex code field |
| Escape | Puts back a code that hasn't been taken yet |
Motion
Its selection indicator slides to the chosen option on `spring.snappy`, inside one track.
With reduced motion: Its thumbs land at once when a key, a typed code or a preset changes the color, instead of gliding there; a drag follows the pointer in the same frame either way.
Layout
It's 216px wide, never wider than its container, with the area at 3:2, the hue track, the code field and any presets 12px apart, the presets six to a row. The hue track's thumb stays inside it end to end, and the track's hit area reaches 28px tall.