ViewToggle
Two icon segments that switch a collection between a grid and a list, each named by its tooltip.
import { ViewToggle } from "@butteryui/react";Demo
When to use it
Use it for
- A collection that reads well as cards or as rows, such as a product catalog
- A list's toolbar, next to its search
Not for
- Other choices than grid and list: use SegmentedControl with iconOnly
- Sections of a page: use Tabs
Examples
Catalog view
A catalog that shows its coffees as cards or as rows.
Cards
Shelf views
Each shelf of the shop keeps its own view in state, so the toggle shows the view kept for the shelf that's open.
Beans as cards
Toolbar toggle
A list's toolbar: search on one side and the view on the other, over the coffees as cards or as rows.
3 coffees
While loading
The toggle disabled while the coffees load, since there's nothing to lay out yet, and back once they're in.
12 coffees as cards
Variants and states
Grid or list
Two icon segments; hover or focus one for its name. The selection glides between them on spring.snappy.
Props
ViewToggle
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | "View" | Names the toggle for screen readers. Defaults to "View". |
labels | Partial<Readonly<Record<ViewMode, string>>> | The segments' names and tooltips, for other languages. Default to "Grid" and "List". | |
value | "grid" | "list" | The chosen value. Pair with onValueChange to control it. | |
defaultValue | "grid" | "list" | The value chosen at first when uncontrolled. Defaults to the first option. | |
onValueChange | ((value: ViewMode) => void) | Called with the new value when the user picks another segment. | |
disabled | boolean | Keeps every segment from being chosen. |
It also takes Omit<ComponentPropsWithRef<"div">, "defaultValue" | "onChange" | "dir">.
Accessibility
A radio group named View (or its label); each segment is a radio named Grid or List, which its tooltip shows. Arrow keys move the choice.
| Keys | What they do |
|---|---|
| Tab | Moves to the chosen segment, the toggle's one stop, and shows its name |
| Arrow Left or Arrow Right | Moves the choice to the other segment |
| Space | Chooses the focused segment |
Motion
Its selection indicator slides to the chosen option on `spring.snappy`, inside one track.
With reduced motion: The pill under the choice appears on the new segment at once instead of sliding there.
Layout
A pill --bt-h-control (34px) tall that keeps its size in a row: two equal segments, each a 16px icon with 8px on either side and 30px tall, the whole segment its hit area. It shows no text; each segment's name is its tooltip.
Related
See it in the roastery demo's wholesale.