Toggle

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add toggle

Usage#

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

export function Example() {
  return <Toggle aria-label="Show grid">Show grid</Toggle>
}

Variants#

outline (the default) is the Toggle Group pill: a framed control whose pressed state is the brand border and a soft halo, with no fill. ghost is bare at rest and takes the accent chip once pressed, the Toolbar's pressed look, for icon toggles in a row of other controls. Each is shown off, then on.

Sizes#

The Toggle Group scale: sm is 32px and md (the default) is 40px, so a lone toggle lines up with a group beside it. iconOnly squares the control around one glyph and steps the glyph up to 20px at md. The 32px control grows its target to 40px (44px on touch) without growing the visual.

Pressed glyph#

ToggleIcon holds two glyphs in one cell and cross-fades them on the toggle's state: the outgoing one shrinks to a quarter, fades and blurs as the incoming one resolves, on a CSS transition, so pressing twice quickly reverses mid-way instead of restarting. Pass the pressed glyph in its fill weight, which is how the system marks a selected state, or a different glyph when on means something else (a slashed microphone). Press them.

With a tooltip#

An icon-only toggle is named by its aria-label: the glyph is not a name. Show that name to sighted users with a Tooltip, and wrap the row in a TooltipGroup so the bubble glides from one toggle to the next.

Controlled#

Hold the state yourself with pressed and onPressedChange. Here it filters the list under it; the count is tabular-nums, so it never jitters as it changes.

Disabled#

disabled dims the control in either state and takes it out of the pointer's way, so a locked setting still shows which way it is set.

API reference#

FAQ#