Toggle
A button that stays down. One control, two states — bold on or off, a filter applied or not. For a set where the choices are alternatives, use ToggleGroup.
Import
import { Toggle } from "@mikenotthepope/substrateui"Variants
default is transparent until pressed, for a dense toolbar where borders would become a grid of boxes. outline carries its border at rest, so the control reads as pressable before you hover it.
Sizes
Each size sets a minimum width as well as a height, so an icon-only toggle comes out square instead of collapsing to the icon's own width.
Controlled
pressed with onPressedChange when the state lives in your app — the toggle then renders what you tell it and nothing else. Note the label changes with the state, so the button says what it is rather than only what it would do.
Thread is pinned to the top.
Accessibility
Base UI renders a real button carrying aria-pressed, so the state is announced and Space and Enter both work. That is the difference between this and a Checkbox: a toggle is a button that stays down, a checkbox is a form value that gets submitted.
An icon-only toggle has no accessible name. Every example above passes aria-label; without one the button is announced as just "button".
The press offset is 1.5px of translate-y, and it collapses under prefers-reduced-motion. The pressed state is also carried by colour, so it does not depend on the motion being seen.
API Reference
toggleVariants is exported alongside the component, for giving a non-Toggle element the same geometry — ToggleGroupItemuses it for exactly that. Every prop not listed goes to Base UI's Toggle; see the Base UI toggle docs for that surface.
| Prop | Type | Default | Description |
|---|---|---|---|
variant | "default" | "outline" | "default" | Transparent until pressed, or carrying a 2px border at rest. |
size | "sm" | "default" | "lg" | "default" | Sets both height and minimum width, so an icon-only toggle stays square. |
pressed | boolean | — | The controlled pressed state. |
defaultPressed | boolean | false | Pressed on first render, when uncontrolled. |
onPressedChange | (pressed: boolean) => void | — | Fired when the toggle should change state. |
disabled | boolean | false | Disable the toggle. |