Skip to content
flyingsalmon

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.

Interests

Installation

npx shadcn@latest add @flyingsalmon/toggle-group

Usage

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.

Activity type

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.

Pick up to 3 interests

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.

Default
Small

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.

One chip disabled
Whole group disabled

Required

Required means the group must hold a value, so the deselect that would empty it does nothing. Try pressing the pressed chip.

Trip pace

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.

Trip pace

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.

Brian Nguyen’s interests

Saved: food
Interests

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

  • Do
    State 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’t
    Hide 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.
  • Do
    Keep 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

KeyDescription
TabMoves focus into the row once, onto the pressed chip or the first one. A second Tab leaves the row.
ArrowLeftArrowRightMoves between chips and wraps at the ends. Disabled and capped chips are skipped.
HomeEndMoves to the first or the last chip.
SpaceEnterToggles the focused chip. In required mode the press that would empty the group does nothing.
ArrowUpArrowDownDo 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.

PropTypeDefaultDescription
modeToggleGroupModeToggleGroupMode.SingleSingle holds a string. Multiple holds an array and adds max.
labelstring–The question the group answers, shown above the chips.
errorstring–Turns the group red and shows the message below it.
valuestring | string[]–The pressed chips when the app controls them: a string in single mode, an array in multiple mode.
defaultValuestring | 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.
maxnumber–Multiple mode only. At the cap, unpressed chips stop toggling.
sizeToggleGroupSizeToggleGroupSize.DefaultDefault and Small match the field heights of the same names.
requiredbooleanfalseBlocks the deselect that would empty the group and marks the label. It is not a submit-time check.
namestring–Posts the pressed values through hidden inputs: one in single mode, one per chip in multiple mode, none while empty.
disabledbooleanfalseDims and disables every chip.
classNamestring–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.

PropTypeDefaultDescription
valuestringRequiredThe value the group reports when this chip is pressed.
iconReactNode–A leading icon, hidden from screen readers.
disabledbooleanfalseTakes this chip out while the rest stay live.
classNamestring–Styles the chip.

  • Radio group

    One answer that stays chosen, shown as a list.
  • Tabs

    For switching the panel underneath, not answering a question.
  • Badge

    A read-only chip that summarises a value.
  • Switch

    A setting that is only on or off.
  • Fields

    The label, error, and wrapper behaviour every field shares.