Skip to content
WunderUI

Toggle

Free

Switch one thing on or off with a button that stays pressed, such as bold text or a filter.

npx wunderui-cli add toggle

Playground

Installation

bash
npx wunderui-cli add toggle

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import { Toggle } from "@/components/ui/toggle"

Then use it:

tsx
import { Bold } from "lucide-react"
import { Toggle } from "@/components/ui/toggle"

export function BoldToggle() {
  return (
    <Toggle aria-label="Bold" defaultPressed>
      <Bold strokeWidth={1.5} />
    </Toggle>
  )
}

Expected result: A 36 px square button with a bold icon on the indigo tint. Press it, or press Enter or Space while it has focus, to turn it off.

When to use

Use Toggle for

  • A state people switch on the spot and see at once, such as bold text, mute or a grid overlay
  • Filters that stay applied while people read a list
  • Icon buttons in a toolbar that keep a mode

Use something else for

  • Switch for a saved setting, with its label beside it
  • Checkbox for a choice in a form that is submitted
  • Radio Button Group for one choice among a few options that look like buttons (a radio group, not a set of toggles)
  • Button for an action that does not stay on

Sizes

Five heights from 32 to 48 px. The icon stays 16 px at every size; the label is 14 px up to Large, 16 px at XL and 18 px at 2XL.

Content

A toggle holds an icon, a label or both. An icon on its own has no text, so give it an aria-label.

States

Off is a white button with a border. On fills with the indigo tint and keeps it on hover; point at a toggle or press Tab to see hover and focus.

Control

By default a toggle keeps its own state. Hold the state yourself when something else on the page depends on it.

Keyboard interactions

The toggle is a native button, so the browser provides focus and activation.

TaborShiftTab
Moves focus to the next or previous toggle. A disabled toggle is skipped.
EnterorSpace
Presses or releases the focused toggle and calls .

Behavior and motion

What the toggle does with state, naming, looks, sizes and motion.

Pressed state
A toggle holds one boolean. Give it a default to start, or control it with a pressed value and change handler, and the state is exposed as aria-pressed.
Naming
A toggle is named by its text. An icon-only toggle has none so it needs an aria-label, and the name stays the same in both states.
Looks
Off is a white fill with a control border, light on hover and subtle while pressed. On is the indigo tint with its border and text, and the indigo tone is tinted at rest and solid while pressed.
Sizes
Five fixed heights: 32, 36, 40, 44 and 48 px, which don't follow density. The icon is 16 px at every size, and the label is 14 px up to large, 16 px at xl and 18 px at 2xl.
Disabled
A disabled toggle is a real disabled button. It keeps its state, drops to 40 % opacity, ignores the pointer and is skipped by Tab.
Focus
Keyboard focus draws the shared focus ring: an indigo border with a 2 px ring directly on the border.
Motion
Colours fade quickly. Nothing moves.
Reduced motion
There is no movement to remove, so reduced motion changes nothing. The colour change stays.

Anatomy

The figure marks a Toggle with an icon and a label. ToggleButton is the same idea for the options of a button group: Checkbox Button Group keeps toggles, Radio Button Group turns them into radios.

  • data-slot="toggle"

    A button that stays pressed or unpressed. Off is a white bordered button and on fills with the indigo tint, and it comes in several sizes, a rounded or pill shape and a neutral or indigo tone.

  • Optional

    An optional 16 px icon in front of the label, or alone when the toggle has an aria-label. It takes the label's colour.

  • Optional

    The button's text. Keep it the same in both states, since the pressed attribute tells assistive technology which state it is in.

  • data-slot="toggle-button"Optional

    The bordered form of a toggle as an option in a Checkbox Button Group or Radio Button Group. In the checkbox group it stays a toggle with a checkbox square, in the radio group it becomes a radio.

  • data-slot="toggle-button-mark"Optional

Best practices

  • Do

    Give an icon-only Toggle an aria-label such as Bold. The pressed attribute announces the state, not the label.

  • Do

    Keep the label and icon the same in both states. A label that flips between Mute and Unmute makes a screen reader say the opposite of what the fill shows.

  • Do

    Put related toggles in one bar with the toolbar role and an aria-label, and use one size and one tone in the row.

  • Do

    Hold the state yourself when something else on the page depends on it, such as a filtered list.

  • Don’t

    Don't use a Toggle to run a one-off action such as Export. An action that doesn't stay on is a Button.

  • Don’t

    Don't use separate Toggles for one choice among several, such as left, centre and right alignment. Use a Radio Button Group, which keeps exactly one option chosen and can't be cleared.

  • Don’t

    Don't put a Toggle in a form to be submitted. Use a Checkbox or a Switch, which belong to the form and have a label beside them.

API reference

One table per part, in the order of the anatomy. Every part also takes the props of the Base UI part it wraps (such as , and ) and the native attributes of its element.

A button that stays pressed or unpressed. Off is a white bordered button and on fills with the indigo tint, and it comes in several sizes, a rounded or pill shape and a neutral or indigo tone.

PropTypeDefaultDescription
pressedboolean—Whether the toggle button is currently pressed. This is the controlled counterpart of .
defaultPressedbooleanfalseWhether the toggle button is currently pressed. This is the uncontrolled counterpart of .
onPressedChange(pressed, eventDetails) => void—Callback fired when the pressed state is changed.
disabledbooleanfalseWhether the component should ignore user interaction.
tone"indigo" | "neutral""neutral" is white when off and tinted indigo when on. is tinted at rest and takes the solid brand fill while it is pressed.
shape"rounded" | "pill""rounded" gives the toggle 8 px corners and is the default; rounds it fully.
size"default" | "lg" | "xl" | "sm" | "2xl""default"The height of the toggle: is 32 px, 36 px, 40 px, 44 px and 48 px.
valueValue—A unique string that identifies the toggle when used inside a toggle group.
nativeButtonbooleantrueWhether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ).
renderReactElement | (props, state) => ReactElement—Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a or a function that returns the element to render.
classNamestring | (state) => string | undefined—CSS class applied to the element, or a function that returns a class based on the component's state.
styleCSSProperties | (state) => CSSProperties | undefined—Style applied to the element, or a function that returns a style object based on the component's state.

The bordered form of a toggle as an option in a Checkbox Button Group or Radio Button Group. In the checkbox group it stays a toggle with a checkbox square, in the radio group it becomes a radio.

PropTypeDefaultDescription
pressedboolean—Whether the toggle button is currently pressed. This is the controlled counterpart of .
defaultPressedbooleanfalseWhether the toggle button is currently pressed. This is the uncontrolled counterpart of .
onPressedChange(pressed, eventDetails) => void—Callback fired when the pressed state is changed.
disabledbooleanfalseWhether the component should ignore user interaction.
indicatorboolean—Draws the radio circle or the checkbox square in front of the label. Default: on inside a RadioButtonGroup / CheckboxButtonGroup when the button has a text label, off for icon-only buttons (no text in children) and outside a group. Pass `f…
valueValue—A unique string that identifies the toggle when used inside a toggle group.
nativeButtonbooleantrueWhether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ).
renderReactElement | (props, state) => ReactElement—Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a or a function that returns the element to render.
classNamestring | (state) => string | undefined—CSS class applied to the element, or a function that returns a class based on the component's state.
styleCSSProperties | (state) => CSSProperties | undefined—Style applied to the element, or a function that returns a style object based on the component's state.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("toggle")
Installnpx wunderui-cli add toggle

The full library index for assistants is at /llms.txt.