Forms

Toggle Group

A group of two-state buttons that share variant and size context.

Preview

import { ToggleGroup, ToggleGroupItem } from '@brika/clay/components/toggle-group';
import { AlignCenter, AlignLeft, AlignRight } from 'lucide-react';

/** Single-selection alignment picker, only one item active at a time. */
export default function ToggleGroupDefaultDemo() {
  return (
    <ToggleGroup type="single" defaultValue="center">
      <ToggleGroupItem value="left" aria-label="Align left">
        <AlignLeft />
      </ToggleGroupItem>
      <ToggleGroupItem value="center" aria-label="Align center">
        <AlignCenter />
      </ToggleGroupItem>
      <ToggleGroupItem value="right" aria-label="Align right">
        <AlignRight />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}

01 Installation

Install

Pull Toggle Group from the barrel for everyday use, or the granular path when you want a tighter bundle.

tsxBarrel1 line

import { ToggleGroup } from "@brika/clay";

tsxGranular1 line

import { ToggleGroup } from "@brika/clay/components/toggle-group";

02 Usage

A minimal example

Drop this into a page. Native HTML attributes pass through to the underlying primitive.

tsxToggle Group.tsx19 lines

import { ToggleGroup, ToggleGroupItem } from '@brika/clay/components/toggle-group';
import { AlignCenter, AlignLeft, AlignRight } from 'lucide-react';

/** Single-selection alignment picker, only one item active at a time. */
export default function ToggleGroupDefaultDemo() {
  return (
    <ToggleGroup type="single" defaultValue="center">
      <ToggleGroupItem value="left" aria-label="Align left">
        <AlignLeft />
      </ToggleGroupItem>
      <ToggleGroupItem value="center" aria-label="Align center">
        <AlignCenter />
      </ToggleGroupItem>
      <ToggleGroupItem value="right" aria-label="Align right">
        <AlignRight />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}

03 Examples

Toggle Group, every way

Disabled

Individual items can be disabled while the rest remain interactive.

GitHub

import { ToggleGroup, ToggleGroupItem } from '@brika/clay/components/toggle-group';

/** Individual items can be disabled while the rest remain interactive. */
export default function ToggleGroupDisabledDemo() {
  return (
    <ToggleGroup type="single" defaultValue="viewer">
      <ToggleGroupItem value="viewer">Viewer</ToggleGroupItem>
      <ToggleGroupItem value="editor">Editor</ToggleGroupItem>
      <ToggleGroupItem value="admin" disabled>
        Admin
      </ToggleGroupItem>
    </ToggleGroup>
  );
}

Multiple

Multiple-selection formatting group, any combination can be active.

GitHub

import { ToggleGroup, ToggleGroupItem } from '@brika/clay/components/toggle-group';
import { Bold, Italic, Underline } from 'lucide-react';

/** Multiple-selection formatting group, any combination can be active. */
export default function ToggleGroupMultipleDemo() {
  return (
    <ToggleGroup type="multiple" variant="outline">
      <ToggleGroupItem value="bold" aria-label="Bold">
        <Bold />
      </ToggleGroupItem>
      <ToggleGroupItem value="italic" aria-label="Italic">
        <Italic />
      </ToggleGroupItem>
      <ToggleGroupItem value="underline" aria-label="Underline">
        <Underline />
      </ToggleGroupItem>
    </ToggleGroup>
  );
}

Text

Text-label items, suitable for view switchers and segmented controls.

GitHub

import { ToggleGroup, ToggleGroupItem } from '@brika/clay/components/toggle-group';

/** Text-label items, suitable for view switchers and segmented controls. */
export default function ToggleGroupTextDemo() {
  return (
    <ToggleGroup type="single" defaultValue="week" variant="outline">
      <ToggleGroupItem value="day">Day</ToggleGroupItem>
      <ToggleGroupItem value="week">Week</ToggleGroupItem>
      <ToggleGroupItem value="month">Month</ToggleGroupItem>
      <ToggleGroupItem value="year">Year</ToggleGroupItem>
    </ToggleGroup>
  );
}

Vertical

Vertical orientation stacks items top-to-bottom with shared dividers.

GitHub

import { ToggleGroup, ToggleGroupItem } from '@brika/clay/components/toggle-group';

/** Vertical orientation stacks items top-to-bottom with shared dividers. */
export default function ToggleGroupVerticalDemo() {
  return (
    <ToggleGroup type="single" defaultValue="week" orientation="vertical">
      <ToggleGroupItem value="day">Day</ToggleGroupItem>
      <ToggleGroupItem value="week">Week</ToggleGroupItem>
      <ToggleGroupItem value="month">Month</ToggleGroupItem>
    </ToggleGroup>
  );
}

04 Accessibility

Accessibility

Arrow keys navigate between items within the group; Space toggles the focused item.
type="single" enforces one active item at a time; type="multiple" allows combinations.
Icon-only items require aria-label on each ToggleGroupItem.
The group wrapper carries role="group", add aria-label to describe the group's purpose.

05 Tokens 3 theme-overridable

Theme tokens

Every CSS variable Toggle Group reads, with its default and the dotted path you'd write in a ThemeConfig JSON to override it. Set any of these in your theme to retune Toggle Group without touching component code.

Toggle Group tokens

3 tokens

ColorFill, border, and text colors.3

--toggle-group-frame-containercolorvar(--input-container)
components.toggleGroup.frameContainer
Background fill of the toggle-group frame. Defaults to the `--input-container` role so a group reads as a single grouped control matching other inputs.
--toggle-group-frame-bordercolorvar(--input-border)
components.toggleGroup.frameBorder
Border color of the toggle-group outer frame. Defaults to the `--input-border` role so the frame matches other input edges.
--toggle-group-divider-colorcolorvar(--input-border)
components.toggleGroup.dividerColor
Color of the 1px separator drawn between adjacent items inside the group (left edge in horizontal orientation, top edge in vertical). Defaults to `--input-border` so dividers blend with the frame.

Override in a theme

Authoring a theme is plain JSON. Drop overrides under components.toggleGroup, the names are camelCase versions of the variable suffix.

jsonmy-theme.json12 lines

{
  "id": "my-theme",
  "name": "My Theme",
  "description": "...",
  "accentSwatches": ["#000"],

  "components": {
    "toggleGroup": {
      "frameContainer": "var(--input-container)"
    }
  }
}

Then apply with applyTheme(myTheme) (see the theming guide), scope it to a subtree with themeToCssVars(myTheme, mode), or consume any token directly in your own JSX with the matching Tailwind utility (e.g. bg-toggle-group-…) — see the chips on each token row.

06 API reference

API reference

Props specific to Toggle Group. Native HTML attributes pass through to the underlying primitive, see the component source on GitHub for the full type signature.

<ToggleGroup />

passthrough

No wrapper-specific props, all attributes pass through to the underlying primitive.

<ToggleGroupContext />

passthrough

No wrapper-specific props, all attributes pass through to the underlying primitive.

<ToggleGroupItem />

passthrough

No wrapper-specific props, all attributes pass through to the underlying primitive.