Toggle

A two-state button that stays pressed until toggled again.

Overview

Toggle is a native button with aria-pressed. Click, Space, and Enter flip it.

It works controlled (pressed) or uncontrolled (defaultPressed). Use Toggle Group for a set of related toggles, and Switch for a setting that applies immediately.

Preview

Customize

Default Pressed

Variant

Size

Disabled

Installation

Add the component with the CLI. It copies the files in and installs anything they depend on.

npx vinyaas add toggle

Usage

1
2
3
4
5
6
7
8
9
import { Toggle } from "@/components/ui/toggle";

export function BoldToggle() {
  return (
    <Toggle aria-label="Toggle bold">
      <BoldIcon />
    </Toggle>
  );
}

Examples

Default

An icon toggle needs an aria-label.

Outline

The outline variant adds a border and keeps the same size.

With text

Text and an icon sit side by side.

Sizes

sm, default, and lg match the Button height scale.

Pressed and disabled

defaultPressed starts on. disabled ignores clicks.

In practice

Independent formatting toggles. Each keeps its own pressed state; use Toggle Group when the choices belong together.

API

Other attributes for the underlying element are passed through.

Name	Type	Default	Description
`pressed`	boolean	—	Controlled pressed state. Omit it for an uncontrolled toggle.
`defaultPressed`	boolean	`false`	Initial pressed state for an uncontrolled toggle.
`onPressedChange`	(pressed: boolean) => void	—	Called with the next state after a click.
`variant`	"default" \| "outline"	`"default"`	Transparent or bordered toggle.
`size`	"sm" \| "default" \| "lg"	`"default"`	Heights match Button: h-8, h-9, and h-10.
`disabled`	boolean	—	Native disabled button. It cannot be toggled.
`className`	string	—	Merged onto the button with cn.

Accessibility

The control is a button with aria-pressed, so assistive technology announces it as a toggle button.

Give icon-only toggles an aria-label that names the action, not the state.
Space and Enter toggle it when it has focus.
disabled blocks activation and uses the native attribute.
Focus uses a visible focus-visible ring.