Toggle

Overview

<Toggle> and <ToggleGroup> are the design system's press-state primitives — buttons that remember whether they're currently "on". <Toggle> is the one-off case (a sidebar collapse, a "show/hide" affordance, a mute button); <ToggleGroup> is the coordinated case (segmented controls, single-pick toolbars, multi-pick formatting bars).

They share a visual language with <Button> on purpose — a pressed toggle should look like a button that's been activated, not a different control altogether.

Why this exists

Two patterns recur across product UIs and deserve a first-class primitive instead of being re-invented per app:

1. Pressed state without a checkbox. Toolbars and segmented controls aren't form fields in the HTML sense — they don't post values, they don't live inside <form>s. Using <input type="checkbox"> styled to look like a button just to get press semantics buys you accessibility headaches (form-control labelling rules, browser default focus rings, tab-order surprises). <Toggle> / <ToggleGroup.Item> is role="button" / role="radio" plus aria-pressed / aria-checked — exactly the right ARIA for the visual.
2. Single-pick vs multi-pick on one component. Toolbars need both ("alignment is a single-pick; bold/italic/underline are multi-pick"). <ToggleGroup type="..."> is the discriminator — same recipe, same keyboard model, same theming, two ARIA contracts.

Modes

<ToggleGroup> is a discriminated union on type:

• type="single" (default) — value is a string. At most one item pressed. Root is role="radiogroup", items are role="radio", arrow keys move focus and activate (the canonical radio pattern). Set required={true} to forbid the user from clearing the active item (one value is always pressed).
• type="multiple" — value is string[]. Each item toggles independently. Root is role="group", items are role="button" with aria-pressed, arrow keys move focus without activating; Space / Enter toggle.

Anatomy

┌────────────────────────────────────────────────────────────┐
│ ToggleGroup (role=radiogroup or role=group)               │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐                    │
│ │  Item    │ │  Item    │ │  Item    │   …                │
│ │  (radio  │ │  (radio  │ │  (radio  │                    │
│ │  or btn) │ │  or btn) │ │  or btn) │                    │
│ └──────────┘ └──────────┘ └──────────┘                    │
└────────────────────────────────────────────────────────────┘

┌────────────────┐
│  Toggle        │   role="button" + aria-pressed
│  (standalone)  │
└────────────────┘

┌────────────────────────────────────────────────────────────┐
│ ToggleGroup (role=radiogroup or role=group)               │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐                    │
│ │  Item    │ │  Item    │ │  Item    │   …                │
│ │  (radio  │ │  (radio  │ │  (radio  │                    │
│ │  or btn) │ │  or btn) │ │  or btn) │                    │
│ └──────────┘ └──────────┘ └──────────┘                    │
└────────────────────────────────────────────────────────────┘

┌────────────────┐
│  Toggle        │   role="button" + aria-pressed
│  (standalone)  │
└────────────────┘

<Toggle> is intentionally standalone — it does not require (and does not consume) a <ToggleGroup> ancestor. Reach for it when you have one toggle, not a coordinated set.

Variants × Colors

Three variants (solid / outline / ghost) × seven colors. The variant determines the off-state chrome; the data-state="on" rules layer the pressed-state tint on top using the color role:

Sizes

Attached (segmented control)

Set attached={true} on <ToggleGroup> to merge neighboring items into a single bar with shared borders and flattened inner corners — the classic "segmented control" look. Rounding adapts to the group's orientation, and uses logical properties (rounded-s-md, rounded-e-md, ms-, me-) so RTL works for free.

Examples

Props

Toggle (standalone)

ToggleGroup (root)

ToggleGroup.Item

Accessibility

• W3C ARIA patterns. type="single" follows the Radio Group pattern (role="radiogroup" + role="radio" + aria-checked + roving tabindex + arrow-activate). type="multiple" follows the Toolbar / press-button pattern (role="group" + role="button" + aria-pressed + all items tabbable + arrow-move-focus-only).
• Keyboard. Arrow keys move (and in single mode, activate). Home/End jump to the first / last enabled item. Space and Enter activate via native <button> semantics. Disabled items are skipped during navigation.
• Roving tabindex (single mode). Only the pressed item is in the tab sequence; if nothing is pressed, the first enabled item is the entry point. Multi-mode keeps every item in the tab sequence — there's no "active" item to rove on, so the user can Tab through marks individually.
• Group labels. A <ToggleGroup> must carry an aria-label or aria-labelledby. Dev builds emit a console warning otherwise.
• Icon-only items. An item whose children are only an icon must supply its own aria-label. Dev builds emit a warning when this is missing.
• Reduced motion. The pressed-state transition shortens to ~120ms under prefers-reduced-motion: reduce. There are no JS-driven animations to disable.
• axe-core. Zero violations across the full 3 × 7 variant × color matrix, in both modes, vertical and horizontal orientations, attached and non-attached.

Theming

defineTheme({
  components: {
    Toggle: {
      defaultProps: { variant: 'outline', size: 'sm', color: 'primary' },
      styleOverrides: {
        root: '',
      },
    },
    ToggleGroup: {
      defaultProps: { variant: 'outline', size: 'sm' },
      styleOverrides: {
        root: '',
        item: 'data-[state=on]:shadow-inner',
      },
    },
  },
});

defineTheme({
  components: {
    Toggle: {
      defaultProps: { variant: 'outline', size: 'sm', color: 'primary' },
      styleOverrides: {
        root: '',
      },
    },
    ToggleGroup: {
      defaultProps: { variant: 'outline', size: 'sm' },
      styleOverrides: {
        root: '',
        item: 'data-[state=on]:shadow-inner',
      },
    },
  },
});

Slot keys: root (and item on ToggleGroup for the attached-position styling).