OptionTiles
Several choices at once, as tiles that take a press anywhere.
import { OptionTiles } from "@butteryui/react";Demo
When to use it
Use it for
- Picking several things at once from up to about eight, each a few words, such as what someone needs at setup
- The answer to the big question in a FullscreenDialog
Not for
- One choice only: use RadioCardGroup or SegmentedControl
- A long list, or a choice inside a form's flow: use Checkbox
Examples
Roast days
The days the roaster runs, kept in state so a button outside the tiles can clear them; Sunday shows but is closed.
Roasting on Monday
Setup needs
What a new roastery needs, the choices listed under the tiles in their order.
Nothing chosen yet
Setup step
A setup step: the big question, its tiles, and Continue, held back until something is chosen.
What will the roastery do first?
Pick as many as you like. You can change them later.
Step 1 of 3
Variants and states
What a roastery needs
Two columns from 480px of room, one under it.
With lines and a closed day
Props
OptionTiles
| Prop | Type | Default | Description |
|---|---|---|---|
labelrequired | string | Names the group for screen readers, such as "What you need". | |
optionsrequired | readonly OptionTile<Value>[] | The tiles, in order. | |
value | readonly Value[] | The tiles chosen. Pair with onValueChange to control them. | |
defaultValue | readonly Value[] | The tiles chosen first when uncontrolled. Defaults to none. | |
onValueChange | ((value: readonly Value[]) => void) | Called with every tile chosen, in the order of options, whenever one is ticked or cleared. |
It also takes Omit<ComponentPropsWithRef<"div">, "defaultValue" | "onChange">.
OptionTile
One tile in `OptionTiles`.
| Field | Type | Default | Description |
|---|---|---|---|
valuerequired | Value | What choosing it adds to the value. | |
labelrequired | string | Its words, in label, which name its checkbox. | |
description | string | A line under the words, which describes its checkbox. | |
disabled | boolean | false | Shows it but stops it being chosen. Defaults to false. |
Accessibility
A group named by label. Each tile is a checkbox named by its words and described by its line; Tab moves from tile to tile and Space ticks one. A chosen tile shows a tick as well as its border, so its state never rests on color alone. Disabled tiles are skipped.
| Keys | What they do |
|---|---|
| Tab | Moves to the next tile, skipping disabled ones |
| Space | Ticks or clears the tile with focus |
Motion
It doesn't move.
With reduced motion: Nothing changes.
Layout
It fills its container: the tiles in one column, or two from 480px of its own width, 8px apart. A tile is at least 40px tall, padded 8px and 12, and grows with its line; its words wrap rather than truncate. The whole tile is the hit area, and a chosen tile's 2px border is drawn inside its edge, so nothing moves.