# ToggleGroup

## Overview

A set of related `<Toggle>` buttons that operate together — either allowing only one selection at a time (`type="single"`) or multiple simultaneous selections (`type="multiple"`). Used for mutually exclusive view modes, filter groups, and formatting toolbars.

---

## When to Use

- View mode switchers (Table / Grid / Kanban)
- Text alignment controls (Left / Center / Right)
- Multi-select filter chips in compact toolbars

---

## Props

### ToggleGroup

| Prop            | Type                     | Default | Required | Description          |
| --------------- | ------------------------ | ------- | -------- | -------------------- |
| `type`          | `'single' \| 'multiple'` | —       | **Yes**  | Selection mode       |
| `value`         | `string \| string[]`     | —       | No       | Controlled value(s)  |
| `defaultValue`  | `string \| string[]`     | —       | No       | Uncontrolled default |
| `onValueChange` | `(value) => void`        | —       | No       | Change handler       |

### ToggleGroupItem

| Prop         | Type     | Required        | Description                       |
| ------------ | -------- | --------------- | --------------------------------- |
| `value`      | `string` | **Yes**         | Unique identifier for this option |
| `aria-label` | `string` | Yes (icon-only) | Accessibility label               |

---

## Examples

### View Mode Switcher

```tsx
import { ToggleGroup, ToggleGroupItem } from 'xertica-ui/ui';
import { LayoutGrid, LayoutList } from 'lucide-react';

<ToggleGroup type="single" defaultValue="list">
  <ToggleGroupItem value="list" aria-label="List view">
    <LayoutList className="size-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="grid" aria-label="Grid view">
    <LayoutGrid className="size-4" />
  </ToggleGroupItem>
</ToggleGroup>;
```

---

## AI Rules

- `type` is **required** — never omit it.
- Always provide `aria-label` for icon-only items.
- For text format toolbars (bold/italic/underline), use `type="multiple"` to allow simultaneous formatting.

---

## Related Components

- [`Toggle`](./toggle.md) — Single standalone toggle
- [`RadioGroup`](./radio-group.md) — Text-heavy single-choice alternatives