Toggle group
A toggle group is a row of chips that answers a question, in single mode or multiple mode, wrapping across lines as needed.
Installation
npx shadcn@latest add @flyingsalmon/toggle-groupUsage
import { useState } from 'react'
import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group'
export function ToggleGroupUsage() {
const [activity, setActivity] = useState('food')
return (
<ToggleGroup label="Activity" value={activity} onValueChange={setActivity}>
<ToggleGroupItem value="food">Food</ToggleGroupItem>
<ToggleGroupItem value="museums">Museums</ToggleGroupItem>
</ToggleGroup>
)
}Examples
Single choice with icons
Single mode is the default. Pressing the pressed chip clears the choice and reports an empty string. Each chip takes an optional leading icon.
Showing food near Alfama.
Multiple with a maximum
At the cap every unpressed chip dims and stops toggling, while pressed chips stay live so the traveller can always back out. The registry renders no counter, so the label states the limit.
Sizes
Size sits on the group, not on each chip. Default and small match the two field heights, so a group lines up with an input or a button.
Disabled
Disable one chip for an option that is unavailable right now, or the whole group to lock it. A capped chip looks the same, because both are unavailable and the label says why.
Required
Required means the group must hold a value, so the deselect that would empty it does nothing. Try pressing the pressed chip.
Error
A group mounted empty is reachable, and a submit while it is empty is your validation error. Pass it as error and the label, the chips, and the message turn red.
Pick a pace before generating the itinerary
In a form
Press a chip and save. name posts each pressed value through hidden inputs, and the card shows what was saved.
Guidelines
When to use
- To answer a question with chips that wrap, such as interests or a trip pace.
- When the traveller may choose several options, or may want to clear a single choice.
When not to use
- Use Radio group when exactly one option must always be chosen and a clear option is not wanted. A radio group cannot be emptied.
- Use Tabs to switch the panel underneath a heading. A toggle group answers a question; tabs navigate.
- Use Badge for a read-only summary, such as the activity types of a trip or the values echoed back on a review screen. A chip the traveller cannot press is not a toggle.
- Use Switch for a setting that is only on or off.
Do and don’t
- DoState the cap in the label when there is one: "Pick up to 3 interests".The group shows no counter. When the remaining chips dim at the cap, the label is the reason on screen.
- Don’tHide the chips the traveller can no longer pick.They dim in place, so the row keeps its shape and the traveller sees what they could swap in by unpressing another.
- DoKeep each chip to a word or two, with a leading icon where it speeds the scan.Chips wrap across lines, and short labels keep the rows even. An answer that needs a sentence belongs in a radio group.
Accessibility
| Key | Description |
|---|---|
| Tab | Moves focus into the row once, onto the pressed chip or the first one. A second Tab leaves the row. |
| ArrowLeftArrowRight | Moves between chips and wraps at the ends. Disabled and capped chips are skipped. |
| HomeEnd | Moves to the first or the last chip. |
| SpaceEnter | Toggles the focused chip. In required mode the press that would empty the group does nothing. |
| ArrowUpArrowDown | Do nothing, because a wrapped row has no vertical order to follow. |
Single mode exposes role="radiogroup" with role="radio" chips carrying aria-checked. Multiple mode exposes a group of buttons carrying aria-pressed. The group is named by its label, takes aria-required in single mode, and an error sets aria-invalid and links the message through aria-describedby. The focus ring appears on keyboard focus only. The accessibility page covers the rules every component follows.
API
ToggleGroup
The group is a field: the fields page describes the label, error, and wrapper behaviour it shares. The value types change with mode.
| Prop | Type | Default | Description |
|---|---|---|---|
| mode | ToggleGroupMode | ToggleGroupMode.Single | Single holds a string. Multiple holds an array and adds max. |
| label | string | – | The question the group answers, shown above the chips. |
| error | string | – | Turns the group red and shows the message below it. |
| value | string | string[] | – | The pressed chips when the app controls them: a string in single mode, an array in multiple mode. |
| defaultValue | string | string[] | – | The starting chips when the app does not control them. |
| onValueChange | (value: string | string[]) => void | – | Called with the next value. Single mode reports an empty string when the chip is cleared. Enforce a chip that stands alone, such as "Anywhere", here: drop the other values when it is pressed, and drop it when another is. |
| max | number | – | Multiple mode only. At the cap, unpressed chips stop toggling. |
| size | ToggleGroupSize | ToggleGroupSize.Default | Default and Small match the field heights of the same names. |
| required | boolean | false | Blocks the deselect that would empty the group and marks the label. It is not a submit-time check. |
| name | string | – | Posts the pressed values through hidden inputs: one in single mode, one per chip in multiple mode, none while empty. |
| disabled | boolean | false | Dims and disables every chip. |
| className | string | – | Styles the wrapper that holds the label, chips, and message, not the chip row. |
ToggleGroupItem
Also takes the Radix toggle group item's own props.
| Prop | Type | Default | Description |
|---|---|---|---|
| value | string | Required | The value the group reports when this chip is pressed. |
| icon | ReactNode | – | A leading icon, hidden from screen readers. |
| disabled | boolean | false | Takes this chip out while the rest stay live. |
| className | string | – | Styles the chip. |