Toggle Group

Visual Hierarchy

Use variant="default" for subtle toggle groups that blend into the interface, and variant="outline" when the group needs to stand out with clear visual boundaries. Choose type="single" for mutually exclusive selections and type="multiple" when users can combine options.

Spacing & Layout

Use spacing={0} (default) for joined items that visually form a single control, ideal for toolbar-style groups. Use spacing={2} or higher to separate items for better visual distinction. When items have both icons and labels, ensure consistent content across all items.

Responsive Behavior

On mobile, consider using size="lg" for better touch targets (minimum 44x44px). For groups with many items, consider wrapping to a second line or switching to a Select on narrow screens. Icon-only items work best on small screens while icon-with-label is preferable on desktop.

Color & Contrast

Pressed items use bg-accent with text-accent-foreground for clear visual feedback. The outline variant adds border-input for additional definition. Disabled states reduce opacity to 50% while maintaining readability. Use data-[state=on]: selectors for custom pressed-state styling.

Keyboard Navigation

• Tab -- Move focus into and out of the toggle group
• ArrowRight / ArrowDown -- Move focus to the next item
• ArrowLeft / ArrowUp -- Move focus to the previous item
• Space or Enter -- Toggle the focused item on or off
• Home -- Move focus to the first item
• End -- Move focus to the last item

Screen Reader Support

• Built on Radix UI ToggleGroup primitive with full ARIA support
• Uses role="group" on the container for screen readers
• Each item announces its pressed state (aria-pressed)
• Icon-only items require aria-label for accessible names
• Add aria-label to the group itself to describe its purpose

Focus Management

Focus is managed as a roving tabindex within the group. Only one item is in the tab order at a time; arrow keys move focus between items. Visible focus ring with 3px width using focus-visible:ring-[3px]. Focused items get z-10 to ensure the focus ring is not clipped by adjacent items.

Touch Targets

Default size items are 36px height (h-9), meeting minimum touch target recommendations. Use size="lg" (44px) for critical touch interactions on mobile. Items with spacing={0} share borders but maintain individual touch targets.

ARIA Attributes

{/* Single selection group with accessible label */}
<ToggleGroup type="single" aria-label="Text alignment">
  <ToggleGroupItem value="left" aria-label="Align left">
    <AlignLeft className="h-4 w-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="center" aria-label="Align center">
    <AlignCenter className="h-4 w-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="right" aria-label="Align right">
    <AlignRight className="h-4 w-4" />
  </ToggleGroupItem>
</ToggleGroup>

{/* Multiple selection group */}
<ToggleGroup type="multiple" aria-label="Text formatting">
  <ToggleGroupItem value="bold" aria-label="Toggle bold">
    <Bold className="h-4 w-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="italic" aria-label="Toggle italic">
    <Italic className="h-4 w-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="underline" aria-label="Toggle underline">
    <Underline className="h-4 w-4" />
  </ToggleGroupItem>
</ToggleGroup>

{/* Disabled item within a group */}
<ToggleGroup type="multiple" aria-label="Text options">
  <ToggleGroupItem value="bold" aria-label="Toggle bold">
    <Bold className="h-4 w-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="strikethrough" disabled aria-label="Toggle strikethrough (unavailable)">
    <Strikethrough className="h-4 w-4" />
  </ToggleGroupItem>
</ToggleGroup>