Clinia UI

Toggle Group

A set of toggles where one or several can be on, such as a view switcher.

shadcn docs →

When to use

  • Switch between a few views of the same content: list and cards, day and week.
  • Turn several related options on and off from one row, such as filters (multiple).

When not to use

  • Switching between panels of different content: use Tabs.
  • A row of actions, such as Export and Share: use Button Group.
  • A choice inside a form that's saved with a button: use Radio Group.

Install

npx shadcn@latest add @clinia/toggle-group

Anatomy

  1. 1Groupdata-slot="toggle-group"spacing={0} · outline
  2. 2Pressed item[data-slot=toggle-group-item][aria-pressed=true]border-emphasis · bg-accent/15
  3. 3Item[data-slot=toggle-group-item][aria-pressed=false]border-input

Clinia rules

  • Pressed items get the Toggle style: a Trust border over a bg-accent/15 tint, with text-foreground.
  • One item is pressed at a time unless you set multiple. For a view switcher, keep one always pressed by ignoring a change to an empty value.
  • spacing={0} with variant="outline" joins the items into one segmented control. The default gap (spacing={2}) keeps them separate.

Do and don't

Do switch between views of the same content.
Don't use it for a row of actions: use Button Group.

States

joined · pressed
focus · joined
multiple · gap
disabled
vertical

Focus cells apply the component's focus-visible classes statically. Toggle the site theme to review both themes.

Accessibility

Built in

  • Base UI makes the group one Tab stop: the arrow keys move focus between items, and each item is a button with aria-pressed.

Your responsibility

  • Name the group with aria-label, such as Layout.
  • Give each icon-only item an aria-label (List, Cards).

How to test

  1. Press Tab: focus enters the group on one item and the Trust ring appears. Tab again leaves the group.
  2. Press Arrow Right and Arrow Left: focus moves between items without pressing them.
  3. Press Enter or Space: the focused item is pressed and, in single mode, the others are released.
  4. With a screen reader, it announces the group name, then each item's label and whether it's pressed.

API

PropValuesDefaultDescription
orientation
horizontalvertical
horizontal

Stacks the items vertically when vertical.

variant
defaultoutline
–

Sets every item's variant. outline gives each item a border; with spacing={0} the items join into one segmented control. Unset, each item keeps its own, default unless it sets one.

size
defaultsmlg
–

Sets every item's height: sm 32px, default 36px, lg 40px. Unset, each item keeps its own.

spacing
number
2

Gap between items, in spacing units. 0 joins them into one segmented control.

All other props come from Base UI Toggle Group.

Related