Toggle

A two-state button that can be on or off, like a standalone toggle in a toolbar.

Overview

Toggle is a two-state button used for toggling a single boolean option. It's commonly used in toolbars for formatting actions (bold, italic) or for standalone toggle buttons like mute/unmute and bookmark/favorite.

Single Toggle

Usage

  <Toggle>Bold</Toggle>


export function Example() {
  return <Toggle>Bold</Toggle>;
}

Variants

Default

  <Toggle>Default</Toggle>

Outline

  <Toggle variant="outline">Outline</Toggle>

Sizes

  <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
    <Toggle size="sm">Small</Toggle>
    <Toggle size="md">Medium</Toggle>
    <Toggle size="lg">Large</Toggle>
  </div>

States

Disabled

  <Toggle isDisabled>Disabled</Toggle>

Pressed

  <Toggle defaultPressed>Pressed</Toggle>

Accessibility

Keyboard Interactions

Key	Action
`Tab`	Moves focus to the toggle
`Enter`	Toggles pressed state
`Space`	Toggles pressed state

Announces "pressed" or "not pressed" based on aria-pressed attribute.

ARIA

Uses <button> element with aria-pressed
aria-disabled="true" when disabled
data-state="on" or "off" for CSS targeting

API Reference

Props

Prop	Type	Default	Description
`pressed`	`boolean`	—	Controlled pressed state
`defaultPressed`	`boolean`	`false`	Uncontrolled default
`onPressedChange`	`(pressed: boolean) => void`	—	Change handler
`variant`	`'default' \| 'outline'`	`'default'`	Visual style
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Toggle size
`isDisabled`	`boolean`	`false`	Disables toggle

AI Decision Guide

Use Toggle when:

Toggling a single boolean option with a button-like appearance
Toolbar formatting buttons as standalone buttons
Muting/unmuting, bookmarking, favoriting

Don't use Toggle when:

On/off for a setting → use Switch
Selecting one from a group → use ToggleGroup or RadioGroup
Triggering a one-time action → use Button

Switch — Settings toggle with track+thumb visual
ToggleGroup — Multiple toggles in a group
Button — Non-toggle action

On this page