Toggle Group

A set of two-state buttons where one or multiple can be active simultaneously — used for text formatting and view switching.

When To Use

Use buttons for explicit user-triggered actions such as submit, save, continue, or open.
Choose the variant and size that matches the action hierarchy in the surrounding view.
Prefer this page when you need to compare action density, icon usage, and loading or disabled states side by side.

When Not To Use

Do not use a button when plain text, static status, or passive decoration would communicate the state just as well.
Do not overload a single view with too many equally prominent buttons; reduce or demote secondary actions first.

Accessibility Notes

Keep a visible label or an equivalent accessible name attached to the control.
Surface validation and helper text programmatically so assistive technologies receive the same context as sighted users.
Preserve the native focus order and keyboard interactions instead of replacing them with custom behavior.

Key Props / API

Key exports

ToggleGroupRoot, ToggleGroupItem

Example Code

import { ToggleGroup, ToggleGroupItem } from "@hilum/ui"
import { AlignLeft, AlignCenter, AlignRight, AlignJustify } from "lucide-react"

<ToggleGroup type="single" defaultValue="left">
  <ToggleGroupItem value="left">
    <AlignLeft className="mr-2 h-4 w-4" />
    Left
  </ToggleGroupItem>
  <ToggleGroupItem value="center">
    <AlignCenter className="mr-2 h-4 w-4" />
    Center
  </ToggleGroupItem>
  <ToggleGroupItem value="right">
    <AlignRight className="mr-2 h-4 w-4" />
    Right
  </ToggleGroupItem>
  <ToggleGroupItem value="justify">
    <AlignJustify className="mr-2 h-4 w-4" />
// ...trimmed for docs

Variants

Single selection

Text alignment with icon and label

Multiple selection

Text formatting options with icons

Icon only

Icon buttons for alignment selection

Outline variant

Text formatting with outline style

Brand variant

Size selection with brand orange styling

Sizes

Size options

Small, default, and large sizes