Shadcn Toggle Group: Segmented Button Controls for React
The shadcn toggle group arranges a set of two-state buttons into one segmented control, where selection can be exclusive, like a text alignment picker, or multiple, like bold, italic, and underline formatting. Built on the Radix UI toggle group primitive and styled with Tailwind CSS, it gives React apps a compact alternative to scattered checkboxes and radio buttons.
The example on this page is a copy-paste toggle group you can adapt in minutes, and the same anatomy scales from icon-only formatting rows to labeled view switchers. It ships as a typed TypeScript component with outline and default styles plus small and large sizes inherited from the toggle.
Where the Shadcn Toggle Group fits
Use a toggle group when a small set of related options should be visible and switchable in one glance: alignment in an editor toolbar, grid versus list view, chart period presets like day, week, and month, or formatting marks that can combine. The pressed state doubles as a status display, showing the active choice without opening anything.
The single mode behaves like a visual radio group, while multiple mode acts as a row of independent toggles. If the options navigate between views with their own content panels rather than setting a value, reach for tabs instead.
Design guidelines
- Keep the set small: Two to five options is the sweet spot. Beyond that, a select or dropdown handles the list better.
- Label icon-only items: Icon toggles need aria-label and ideally a tooltip, since alignment glyphs are not universally obvious.
- Make the pressed state unmistakable: Contrast between on and off must survive a quick glance, not just close inspection.
- Guard against empty selection: In single mode decide whether deselecting everything is valid, and keep a default pressed item if a value is always required.
- Group only related options: Every item in the segment should answer the same question. Mixing unrelated toggles breaks the mental model.
Reasons to use it
- Two selection modes: The type prop switches between exclusive single selection and independent multiple selection with no extra logic.
- Roving focus built in: The group is one tab stop, and arrow keys move between items, matching toolbar keyboard conventions.
- Correct ARIA semantics: Items expose pressed or checked state appropriately for the chosen mode, so screen readers announce the control accurately.
- Variant and size inheritance: Outline and default variants plus size options come from the toggle, keeping toolbars visually consistent.
Pairing with other components
A single standalone option belongs to the toggle component, and grouped action buttons that trigger commands rather than hold state belong in a button group. Editor toolbars often line up a toggle group next to a select for font size and a separator between clusters.
View switchers pair the group with the content it controls, such as a chart whose period follows the pressed item. When choices are exclusive but deserve full labels and descriptions, a radio group communicates better than compact segments.
Primitive support
Underneath is the Radix UI Toggle Group primitive, which manages the selection model, roving tabindex, and ARIA state for both single and multiple modes. Setup and props are documented in the shadcn toggle group docs.
Base UI provides its own Toggle Group with matching behavior, so projects on Base UI can restyle it with the same Tailwind CSS classes used in this example.