Skip to main content

​
Overview

Single toggle
Toggle group
Toggle is a pressable button that maintains a pressed/active state. Unlike Switch (which is for binary settings), Toggle is used for actions: formatting (bold/italic), view switching (grid/list), and filter activation.
Use ToggleGroup when toggles are related and should behave as a group — either "single" (radio-like) or "multiple" (checkbox-like). Use standalone Toggle for independent on/off states.

​
Installation

​
Usage

​
Variants

​
Single Toggle (Icon Only)

Off → On

​
With Label

Off → On

​
Toggle Group — Single Select

One item can be active at a time (radio-like behavior).

​
Toggle Group — Multi Select (Text Formatting)

Multiple items can be active simultaneously (checkbox-like behavior).
Bold + Underline active

​
Outline Variant

​
Sizes

​
API Reference

​
Toggle

​
boolean
Controlled pressed state.
​
(pressed: boolean) => void
Callback fired when pressed state changes.
​
boolean
default:"false"
Uncontrolled default pressed state.
​
boolean
default:"false"
Disables the toggle.
​
string
default:"default"
Visual style. Values: default · outline
​
string
default:"md"
Button size. Values: sm · md · lg
​
string
Accessible label — required for icon-only toggles where the visible content doesn’t describe the action.

​
ToggleGroup

​
string
required
Selection mode. "single" allows one active item; "multiple" allows many.
​
string | string[]
Controlled value. String for single, array for multiple.
​
(value: string | string[]) => void
Callback fired when selection changes.
​
string | string[]
Uncontrolled default value.
​
string
default:"md"
Applies to all items in the group. Values: sm · md · lg

​
Accessibility

  • Toggle renders as a <button> with aria-pressed="true|false" reflecting the current state
  • Icon-only toggles must have aria-label describing the action (e.g. "Toggle bold", not "B")
  • ToggleGroup uses role="group" with aria-label describing the group
  • Keyboard: Space/Enter toggles the focused item; Arrow keys navigate within ToggleGroup
  • State changes are announced to screen readers via aria-pressed

​
Do’s & Don’ts

Do

  • Use ToggleGroup type="single" for mutually exclusive view modes (grid/list)
  • Use ToggleGroup type="multiple" for independently combinable states (bold + italic)
  • Always provide aria-label for icon-only toggles
  • Use Toggle for UI state (view mode, filter) and Switch for settings (on/off preferences)

Don't

  • Don’t use Toggle as a navigation element — use Tabs instead
  • Don’t use Toggle for binary settings that persist across sessions — use Switch
  • Don’t use Toggle for form submission — use a Button or Checkbox
  • Don’t put too many items in a ToggleGroup — limit to 4–5 maximum