Choice grid
A line-up of choices as tiles — a visual, a name, a line: a radio group with roving focus when selectable, a named showcase otherwise; sober by default, a select screen in the arcade flavour.
Web only — React, from @krizaka/ui/choice-grid. Beta: its API may still change in a minor version.
When to use
- Choosing one of a few options that are best recognised by a picture: a plan, a persona, a team, an avatar, a side.
- Presenting a line-up at the top of a told page (products, characters, members), without selection.
When not to use
- More than eight options, or options without a visual.Use instead: Radio group
- Switching between views of the same content.Use instead: Tabs
- Picking several interests or tags.Use instead: Chip
Installation
Install
npm install @krizaka/ui @krizaka/tailwind @krizaka/tokens tailwindcssStyles
@import "tailwindcss";
@import "@krizaka/tailwind";
@import "@krizaka/ui/tailwind.css";Import
import { ChoiceGrid } from "@krizaka/ui/choice-grid";Examples
Choose a plan
Selectable: three plans as tiles, the arrow keys move and choose.
Step 1 of 3You can change it at any time.
A line-up (arcade)
The select screen: each tile in its brand, the corners locking on each one in turn.
Props
A line-up of choices as tiles. With onValueChange (or value), a radio group: one tab stop, the arrow keys move
and choose, Home/End jump, the chosen tile is marked. With href on the items, a list of links. Otherwise a list
named by label that presents the line-up.
| Prop | Type | Default | Description |
|---|---|---|---|
itemsrequired | readonly ChoiceItem[] | — | The choices, in reading order. |
labelrequired | string | — | The accessible name of the group (“Choose your plan”) — passed translated. |
animated | boolean | true | The tiles' arrival on mount (arcade: the corners locking one by one, the gauges filling). Always off under
prefers-reduced-motion. |
brand | string | — | A brand scope for the whole grid (orochia → .brand-orochia). |
caption | ReactNode | — | A line beside the tag: what the choice means. |
columns | number | min(items, 4) | The number of columns (one on a phone). |
defaultValue | string | — | The chosen id at first (uncontrolled). |
linkAs | LinkComponent | — | The app's link component for the tiles' internal hrefs (Next's Link); an <a> otherwise. |
onValueChange | ((id: string) => void) | — | Makes the grid a radio group: called with the id chosen by click, Enter, Space or the arrow keys. |
prompt | ReactNode | — | A call above the tiles, larger (“Choose your plan”). |
tag | ReactNode | — | A short mono line above the grid (a step, a tag). |
value | string | — | The chosen id (controlled). |
variant | StoryVariant | default | default: sober tiles. arcade: the select screen — the brand's light on each card, corners that lock, a flash. |
Accessibility
- Selectable:
role="radiogroup"named bylabel, each tile aradiowitharia-checked; the chosen one is also marked by a ring and a check, not by colour alone. - Not selectable: a list named by
label, one item per tile. - The visuals are decorative: the name carries the meaning. The arrival and the corner locks stop under
prefers-reduced-motion.
Keyboard
| Keys | Action |
|---|---|
| Tab | Moves into the group, onto the chosen tile, then out of it. |
| Arrow keys | Move to the next or previous tile and choose it. |
| Home / End | Move to the first or last tile and choose it. |
| Space / Enter | Chooses the focused tile. |
Best practices
- Two to four tiles per row: the name short, the line under it saying what the choice gives.
- Pass
label: the group's accessible name, also when the tag and caption say it visually. - Keep the arcade flavour for a told page; in a product flow, the default tiles.
Related components
Generated from the code of @krizaka/ui 2.10.0: its meta.ts, its examples and its types.Edit this documentation on GitHub