Docs / Primitives / Toggle

Toggle

A two-state button, and a group of them with single or multiple selection. Dark mode is controlled by the parent through isDark; the toggle below lives outside the component.

Dark mode

Variants and sizes

Controlled

Bold is off

Disabled

Single selection

Alignment: left

Multiple selection, joined

Formatting: bold

Vertical

Grid starts pressed, but Tab enters the group on its first item, like Base UI.

Consumer handlers

Your own onclick or onkeydown runs first and the built-in behavior still runs.

Consumer clicks: 0

Last key: none

Large pressed: not reported

Items added later

Inside a form

type and form are ignored, like Base UI, so a toggle never submits a form.

Form submits: 0

Disabled group

Differences from upstream

Built on plain buttons instead of the Base UI Toggle and ToggleGroup primitives (React-only), so TogglePrimitive and ToggleGroupPrimitive are not exported. Props follow Base UI: pressed, defaultPressed, onPressedChange, value, defaultValue, onValueChange, multiple (default false), loopFocus, disabled, orientation, plus upstream's spacing.
A consumer onclick or onkeydown runs before the built-in handler, like Base UI. To skip the built-in behavior, call event.preventDefault(); Base UI's event.preventBaseUIHandler() does not exist on DOM events.
The Tab stop starts on the first item in DOM order and then follows focus, like Base UI 1.4.1. Two deliberate changes: when the first item is disabled the stop moves to the next enabled item (Base UI leaves the group with no Tab stop), and the remembered stop follows the focused item rather than its position when items are added or removed.
Like Base UI, type and form are ignored: a toggle always renders type="button" and never joins a form.
className and class are both accepted; children is a Svelte snippet.
The before-pseudo shadow, touch hit-area, and icon sizing utilities from upstream's class list are not ported; variants and sizes are.
Accepts isDark and onIsDarkChange; it reflects isDark and never calls onIsDarkChange.
ToggleGroup renders data-orientation but not Base UI's aria-orientation, which ARIA does not allow on role="group".

Back to all components