Toggle

Pressed or unpressed control for formatting and view options. Group toggles when choices share a context.

Examples

Single

Group

Multiple

Overview

Toggle is a two-state button. Use alone for a single option, or wrap several in ToggleGroup for alignment and formatting toolbars. Groups default to single selection; set multiple when more than one can stay pressed.

tsx

import { Toggle, ToggleGroup } from "@standard-ui/react"

<Toggle defaultPressed>Bold</Toggle>

<ToggleGroup defaultValue={["center"]}>
  <Toggle value="left">Left</Toggle>
  <Toggle value="center">Center</Toggle>
  <Toggle value="right">Right</Toggle>
</ToggleGroup>

Usage

Single toggle

Use defaultPressed or controlled pressed / onPressedChange. Provide an accessible name with visible text or aria-label.

tsx

<Toggle aria-label="Bold" defaultPressed>
  Bold
</Toggle>

Toggle group

Each child Toggle needs a value. The group tracks pressed values as an array via defaultValue or value.

tsx

<ToggleGroup
  aria-label="Text alignment"
  defaultValue={["left"]}
>
  <Toggle value="left">Left</Toggle>
  <Toggle value="center">Center</Toggle>
  <Toggle value="right">Right</Toggle>
</ToggleGroup>

Multiple

Pass multiple so several toggles can stay pressed — useful for Bold / Italic / Underline. Without it, pressing one clears the others.

tsx

<ToggleGroup multiple defaultValue={["bold"]}>
  <Toggle value="bold">Bold</Toggle>
  <Toggle value="italic">Italic</Toggle>
</ToggleGroup>

API

Toggle and ToggleGroup accept Base UI props for pressed state and group selection.

Toggle

Prop	Type	Default	Description
defaultPressed	boolean	false	Uncontrolled initial pressed state.
pressed	boolean	—	Controlled pressed state.
onPressedChange	(pressed: boolean, event) => void	—	Called when pressed state changes.
value	string	—	Identifies the toggle inside a group.
disabled	boolean	false	Disables the toggle.

ToggleGroup

Prop	Type	Default	Description
defaultValue	string[]	—	Uncontrolled pressed values.
value	string[]	—	Controlled pressed values.
onValueChange	(value: string[], event) => void	—	Called when group selection changes.
multiple	boolean	false	Allow more than one toggle pressed.
disabled	boolean	false	Disables the entire group.

Guidelines

Do

Use toggles for formatting and view options that stay pressed
Use multiple only when several options can apply at once
Prefer a switch for a single on/off setting that takes effect immediately

Don't

Don't use toggles for navigation — use links or tabs
Don't omit value on toggles inside a group
Don't force cursor-pointer — keep the platform default for controls