Toggle Group

When to UseCopy Anchor Link

• for formats that combine, such as bold, italic, and underline, when multiple is set
• for a set where at most one option is on and a second click clears it, when multiple isn’t set
• to place related Toggles behind one stop for Tab so that users move between them with the arrow keys

When Not to UseCopy Anchor Link

• for a set that keeps one option selected (use a Segmented Control)
• for a single option that turns on and off (use a Toggle)
• for actions that have no state (use a Button Group)
• for options that are submitted with a form (use a Checkbox or a Radio Group)
• for views that switch in place (use Tabs)

See Segmented Control for a comparison of the Toggle Group, the Segmented Control, and Tabs.

AnatomyCopy Anchor Link

An item is a Toggle and has the same parts.

SizesCopy Anchor Link

To set the size of all items, use size on ToggleGroup. variant works the same way. A value on the group overrides the same prop on an item so that a group has one size. See Sizing for the rule on controls in a row and Toggle for the text and icon sizes.

StatesCopy Anchor Link

An item has the states of a Toggle, and a pressed item needs the same mark. To disable all items, set disabled on ToggleGroup.

BehaviorCopy Anchor Link

ToggleGroup keeps the pressed state of its items in one value and moves focus between them.

SelectionCopy Anchor Link

By default, at most one item is on: when users click another item, the selection moves to it, and when they click the pressed item, the selection is cleared. If multiple is set, each item turns on and off independently. In both cases, the value is an array that contains the value of each pressed item.

SpacingCopy Anchor Link

spacing sets the gap between items in units of 4px. By default, it is 2, which is a gap of 8px. If you set spacing={0}, the items are joined.

OrientationCopy Anchor Link

To stack the items, set orientation="vertical". Users then move focus with ArrowDown and ArrowUp, and ArrowRight and ArrowLeft do nothing.

AccessibilityCopy Anchor Link

Base UI’s Toggle Group renders a div with role="group" and makes the set one stop for Tab. Users move focus between the items with the arrow keys, Home, and End, and press Enter or Space to turn the focused item on or off.

To name a Toggle Group for screen readers, set aria-label, as “Text formatting” does in the preview.

InstallationCopy Anchor Link

npx shadcn@latest add @summit/toggle-group

The CLI also adds @summit/toggle.

UsageCopy Anchor Link

import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';
import { TextBIcon, TextItalicIcon, TextUnderlineIcon } from '@phosphor-icons/react';

<ToggleGroup multiple aria-label="Text formatting">
    <ToggleGroupItem value="bold" aria-label="Bold">
        <TextBIcon />
    </ToggleGroupItem>
    <ToggleGroupItem value="italic" aria-label="Italic">
        <TextItalicIcon />
    </ToggleGroupItem>
    <ToggleGroupItem value="underline" aria-label="Underline">
        <TextUnderlineIcon />
    </ToggleGroupItem>
</ToggleGroup>;

Mark a Pressed ItemCopy Anchor Link

To change the icon of a pressed item, pass a function to render on the item. The function receives state.pressed, as on a Toggle.

<ToggleGroupItem
    value="bold"
    aria-label="Bold"
    render={(props, state) => (
        <button type="button" {...props}>
            <TextBIcon weight={state.pressed ? 'bold' : 'regular'} />
        </button>
    )}
/>

Join the ItemsCopy Anchor Link

To join the items, set spacing={0}. If you also set variant="outline", the items share their borders.

<ToggleGroup variant="outline" spacing={0} multiple aria-label="Text formatting">
    <ToggleGroupItem value="bold" aria-label="Bold">
        <TextBIcon />
    </ToggleGroupItem>
    <ToggleGroupItem value="italic" aria-label="Italic">
        <TextItalicIcon />
    </ToggleGroupItem>
</ToggleGroup>

API ReferenceCopy Anchor Link

Other props of ToggleGroup are passed to Base UI’s Toggle Group. See the Base UI Toggle Group documentation for value, defaultValue, onValueChange, multiple, loopFocus, and disabled. Other props of ToggleGroupItem are passed to Base UI’s Toggle. See the Base UI Toggle documentation for value and render.

ToggleGroupCopy Anchor Link

ToggleGroupItemCopy Anchor Link

ToggleGroupItem accepts variant and size as a Toggle does, and the group’s values override them.