Toggle

A toggle holds a boolean that stays on until pressed again — the board's filter strip above is the archetype. Control it (pressed + onPressedChange) whenever the state is real, which is almost always.

A single toggle

On its own it reads as on/off. Pair it with ToggleIndicator and it shows what it will do rather than what it did.

Usage

import { Toggle, ToggleIndicator } from "@kanzo-tech/ui";

<Toggle aria-label="Past its due date" defaultPressed>
  <ClockIcon />
</Toggle>

A toggle is a button that remembers, not a checkbox: it carries aria-pressed, so give it an aria-label when the only child is an icon.

Variants

Only the two button variants that read as a surface you can press in are allowed — default and destructive would fight the pressed state.

Sizes

With indicator

ToggleIndicator swaps its children for fallback when the toggle is not pressed, so the icon follows the state without any of your own conditional rendering.

Disabled

As a group

ToggleGroup holds several toggles as one control and owns their variant, size and spacing — ToggleGroupItem reads all three off it, so a group is styled in one place and an item never disagrees with its neighbours.

import { ToggleGroup, ToggleGroupItem } from "@kanzo-tech/ui";

<ToggleGroup aria-label="Text style" onValueChange={(d) => setMarks(d.value)} value={marks} variant="outline">
  <ToggleGroupItem aria-label="Bold" value="bold">
    <BoldIcon />
  </ToggleGroupItem>
</ToggleGroup>

multiple defaults to true, which is the opposite of Ark's: a group of independent marks is what a toggle group usually is, and one-of-N is SegmentGroup's or Tabs's job far more often than it is this one's. Pass multiple={false} where the choice really is exclusive and deselecting is meant to be possible — that is the one thing SegmentGroup will not do.

spacing is a gap in spacing units and defaults to 0, which is not "no styling" but the segmented look: at zero the items drop their inner radii, only the ends stay round, and an outline group collapses its shared borders into single hairlines. Any other value separates them into individual toggles.

orientation="vertical" stacks the group and moves the rounding to the top and bottom ends — the activity rails in the showcases are this, and the PanelRail block is the composed version.

API Reference

useToggleGroup is Ark's useToggleGroupContext, re-exported: it reads the group's value and setValue from anywhere inside one.

toggleVariants is exported for a pressed/unpressed control of your own — it is buttonVariants plus the data-[state=on] wash, which is the part worth not rewriting.

Extends Toggle.Root from Ark, so pressed, defaultPressed, onPressedChange and disabled pass through.

ToggleProps is exported, so a wrapper can take the same props without restating them.