Toggle Group

A set of two-state buttons that can be toggled on or off. Built on top of Radix UI Toggle Group primitive.

Installation

npm install @darksnow-ui/toggle-group

Peer Dependencies

npm install react react-dom

Usage

import { ToggleGroup, ToggleGroupItem } from "@darksnow-ui/toggle-group"
import { Bold, Italic, Underline } from "lucide-react"

export function ToggleGroupExample() {
  return (
    <ToggleGroup type="multiple">
      <ToggleGroupItem value="bold" aria-label="Bold">
        <Bold className="h-4 w-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="italic" aria-label="Italic">
        <Italic className="h-4 w-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="underline" aria-label="Underline">
        <Underline className="h-4 w-4" />
      </ToggleGroupItem>
    </ToggleGroup>
  )
}

Components

ToggleGroup

The root container for toggle group items.

| Prop | Type | Default | Description | |--------------|-----------------------------------|---------|--------------------------------| | type | "single" | "multiple" | "single" | Selection behavior | | value | string | string[] | - | Controlled value(s) | | defaultValue | string | string[] | - | Default value(s) | | onValueChange| function | - | Called when value changes | | disabled | boolean | false | Disables all items | | orientation | "horizontal" | "vertical" | "horizontal" | Group orientation | | className | string | - | Additional CSS classes |

ToggleGroupItem

A single toggle item within the group.

| Prop | Type | Default | Description | |-----------|-------------------|---------|------------------------| | value | string | - | The item's value | | disabled | boolean | false | Disables this item | | className | string | - | Additional CSS classes|

Examples

Text Formatting Toolbar

function FormattingToolbar() {
  const [value, setValue] = useState<string[]>([])

  return (
    <ToggleGroup 
      type="multiple" 
      value={value} 
      onValueChange={setValue}
    >
      <ToggleGroupItem value="bold">
        <Bold className="h-4 w-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="italic">
        <Italic className="h-4 w-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="underline">
        <Underline className="h-4 w-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="strikethrough">
        <Strikethrough className="h-4 w-4" />
      </ToggleGroupItem>
    </ToggleGroup>
  )
}

Text Alignment (Single Selection)

function TextAlignment() {
  const [alignment, setAlignment] = useState("left")

  return (
    <ToggleGroup 
      type="single" 
      value={alignment} 
      onValueChange={(value) => value && setAlignment(value)}
    >
      <ToggleGroupItem value="left">
        <AlignLeft className="h-4 w-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="center">
        <AlignCenter className="h-4 w-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="right">
        <AlignRight className="h-4 w-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="justify">
        <AlignJustify className="h-4 w-4" />
      </ToggleGroupItem>
    </ToggleGroup>
  )
}

Vertical Toggle Group

<ToggleGroup type="single" orientation="vertical">
  <ToggleGroupItem value="top">
    <ArrowUp className="h-4 w-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="center">
    <Minus className="h-4 w-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="bottom">
    <ArrowDown className="h-4 w-4" />
  </ToggleGroupItem>
</ToggleGroup>

View Mode Selector

function ViewModeSelector() {
  const [viewMode, setViewMode] = useState("grid")

  return (
    <ToggleGroup 
      type="single" 
      value={viewMode} 
      onValueChange={(value) => value && setViewMode(value)}
    >
      <ToggleGroupItem value="list">
        <List className="h-4 w-4" />
        <span className="ml-2">List</span>
      </ToggleGroupItem>
      <ToggleGroupItem value="grid">
        <Grid3X3 className="h-4 w-4" />
        <span className="ml-2">Grid</span>
      </ToggleGroupItem>
      <ToggleGroupItem value="card">
        <LayoutGrid className="h-4 w-4" />
        <span className="ml-2">Card</span>
      </ToggleGroupItem>
    </ToggleGroup>
  )
}

Accessibility

• Full keyboard support (Arrow keys, Space, Enter)
• Screen reader accessible with proper ARIA attributes
• Focus management between items
• Group and item role announcements
• Pressed state announcements

Styling

Uses DarkSnow UI design tokens for consistent theming with grouped button styling.

Best Practices

1. Clear visual grouping: Items should visually appear as a cohesive group
2. Consistent icons: Use similar icon styles within a group
3. Logical ordering: Arrange items in a logical sequence
4. Appropriate selection type: Use "single" for exclusive choices, "multiple" for independent options
5. Accessible labels: Provide meaningful aria-label attributes

Related Components

• Toggle - Individual toggle controls
• Radio Group - Exclusive selection groups
• Checkbox - Multiple selection controls