SwatchGrid
A grid of color and gradient swatches to pick one from, like radio buttons.
import { SwatchGrid } from "@butteryui/react";Demo
When to use it
Use it for
- Picking a background or fill from presets, such as the palettes in @butteryui/core/palettes
Not for
- Any color at all: use ColorDot
- A few named options: use SegmentedControl
Examples
Background picker
The gradient presets as swatches, chosen into state that also paints a preview beside its name.
Lilac background
Background section
An inspector's background section: the fill type picks the swatches in the grid's row, and Reset puts it all back.
Background
Brand colors
A few colors of your own, typed to their values, in rows of four.
Accent: Sky
Photo background
A disabled grid: no swatch can be chosen while a picture covers the slide's fill.
The picture covers the fill
Variants and states
Gradients
buttery's 24 gradients, six to a row. The chosen one gets the selection ring at once.
Solids and disabled
Props
SwatchGrid
| Prop | Type | Default | Description |
|---|---|---|---|
labelrequired | string | What the swatches choose, such as "Background". It names the group. | |
swatchesrequired | readonly Swatch<Value>[] | The swatches, row by row. | |
value | Value | The chosen swatch's value. Pair with onValueChange to control it. | |
defaultValue | Value | The value chosen at first when uncontrolled. | |
onValueChange | ((value: Value) => void) | Called with the value of the swatch chosen. | |
columns | 4 | 5 | 6 | 7 | 8 | 6 | Swatches per row. Defaults to 6. |
disabled | boolean | Keeps every swatch from being chosen. |
It also takes Omit<ComponentPropsWithRef<"div">, "defaultValue" | "onChange" | "children">.
Swatch
One swatch: a value to choose, its name and how it's painted.
| Field | Type | Default | Description |
|---|---|---|---|
valuerequired | Value | What choosing it sets the grid's value to. | |
labelrequired | string | Its name for screen readers and the tooltip, such as "Peach". | |
fillrequired | string | A CSS background: a color, or a gradient from gradientCss in @butteryui/core/palettes. |
Accessibility
A radiogroup named by label; each swatch is a radio named by its label, and the chosen one is checked. It's one tab stop, on the chosen swatch. Arrow keys move across rows and up and down columns, choosing as they go; Home and End reach the first and last.
| Keys | What they do |
|---|---|
| Tab | Moves into the grid on the chosen swatch, or the first when none is, and on out of it |
| Arrow Right or Arrow Left | Chooses the next or previous swatch, wrapping from the last to the first and back |
| Arrow Down or Arrow Up | Chooses the swatch below or above, staying put on the last or first row |
| Home or End | Chooses the first or last swatch |
| Space or Enter | Chooses the focused swatch |
Motion
It doesn't move.
With reduced motion: Nothing changes.
Layout
It fills its container's width with columns square swatches to a row (6 by default), 8px apart, and wraps the rest onto more rows; each swatch is a square share of the width and the whole square is its hit area. It shows no text: each swatch's name is its title.
Related
See it in the Deckhand demo.