Toggles

Toggle is a pressable button that holds an on/off state, styled from the shared toggleVariants. Reach for it for a standalone binary control such as a formatting button (bold) or a show/hide switch where the state is conveyed by the button looking pressed. For a set of related toggles use Segmented Controls instead.

Live demo

The interactive story below runs from the deployed Storybook.

Usage

Source: toggle.tsx

import { Toggle } from "@beacon/design-system";

// Default
<Toggle>Toggle</Toggle>

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

// Starts pressed (uncontrolled)
<Toggle defaultPressed>Pressed</Toggle>

// Disabled
<Toggle disabled>Disabled</Toggle>

Props

Toggle forwards every prop from the Radix Toggle.Root and adds the variant props below.

Prop	Type	Default	Description
variant	"default" | "outline"	"default"	Visual style. outline adds a border.
size	"default" | "sm" | "lg"	"default"	Control height and padding.
pressed	boolean	—	Controlled on/off state. Pair with onPressedChange.
defaultPressed	boolean	false	Uncontrolled starting state.
onPressedChange	(pressed: boolean) => void	—	Fires when the pressed state changes.
disabled	boolean	false	Greys out and blocks interaction.
children	ReactNode	—	Icon or short label shown inside the button.
className	string	—	Extra classes on the root.

The toggleVariants helper is also exported for composing custom toggle-styled elements.

When to use

• A single on/off control where the pressed appearance carries the meaning (bold, mute, pin).
• Icon-only buttons that retain a state, such as a star/favorite toggle.
• Toolbar buttons that should look depressed while active.

Do not use Toggle for a labeled settings on/off where a clear track-and-knob affordance is expected; use the Switch component there. For mutually exclusive choices in a row, use Segmented Controls.