ToggleGroup

A toggle group is a row of buttons in a gray track that people press on and off: Bold, Italic and Underline, or a row of filters, each selectable on its own (Built from existing parts). With multiple, any number can be on; without it, one or none. A pressed button is a yellow sticker.

跟随页面浅色深色并排

When to use

The full table is in Choosing a component.

Anatomy

• ToggleGroup: the track, in fill-muted. Its value is the list of pressed items. Required.
• ToggleGroupItem: one 32px button, identified by its value. Required, at least 2.
  • An icon: optional, 16px. It can stand alone (aria-label required, see Accessibility).
  • ToggleGroupLabel: the visible label. It truncates when the row is too narrow.

Variants

跟随页面浅色深色并排

跟随页面浅色深色并排

States

跟随页面浅色深色并排

跟随页面浅色深色并排

Behavior

• A horizontal group wraps its items onto a new row when they don't fit, and never grows wider than its container.
• Pressing a pressed item turns it off, in both variants.
• Items sit 3px inside the track and 3px apart, like the segments of a SegmentedControl.
• Items are 32px high and don't extend their hit area to 44px. On touch screens that is below the hit target.

Content

• Label each item with what it turns on, in Title Case: Bold, Numbered List (Writing).

Accessibility

• ToggleGroup wraps the Base UI ToggleGroup and each ToggleGroupItem the Base UI Toggle: every item is a button with aria-pressed, and the arrow keys move focus between items in the direction of orientation, wrapping at the ends (loopFocus).
• Name the group with aria-label after what it controls: "Text formatting", "Text alignment".
• Give every icon-only item an aria-label ("Align left"), and hide its icon (aria-hidden).

Rules

• Don't use a toggle group to switch views or sections: one view is always shown, and a toggle group can be left with none. Use a SegmentedControl or Tabs.