# Toggle group

> A segmented control: toggle buttons joined into one, or links where each segment is its own page.

A toggle group is a row of choices that reads as a single control. Build it from `items`, and say which one is on with `value`.

## Basic group

```javascript
toggleGroup({
  label: 'Text alignment',
  value: 'center',
  items: [
    { value: 'left', label: 'Left' },
    { value: 'center', label: 'Center' },
    { value: 'right', label: 'Right' },
  ],
})
```

## Plain strings

```javascript
toggleGroup({ label: 'Density', value: 'comfortable', items: ['compact', 'comfortable', 'spacious'] })
```

## Links

This is the form a static site usually wants: each segment is a page. Items with an `href` render as anchors and the active one is marked `aria-current="page"` — not `aria-pressed`, because a link is not a button you have pushed in.

```javascript
toggleGroup({
  label: 'Section',
  value: 'ui',
  items: [
    { value: 'docs', label: 'Docs', href: '/docs' },
    { value: 'ui', label: 'UI', href: '/ui' },
    { value: 'examples', label: 'Examples', href: '/examples' },
  ],
})
```

## More than one on

Pass an array as `value`. The container is a plain `group` either way — a `radiogroup` would be wrong, since these are pressed buttons rather than radios.

```javascript
toggleGroup({
  label: 'Formatting',
  value: ['bold', 'underline'],
  items: [
    { value: 'bold', label: 'Bold' },
    { value: 'italic', label: 'Italic' },
    { value: 'underline', label: 'Underline' },
  ],
})
```

## Sizes and variants

```javascript
stack({ gap: 'md' },
  toggleGroup({ size: 'sm', label: 'Small', value: 'a', items: ['a', 'b', 'c'] }),
  toggleGroup({ size: 'md', label: 'Medium', value: 'a', items: ['a', 'b', 'c'] }),
  toggleGroup({ size: 'lg', label: 'Large', value: 'a', items: ['a', 'b', 'c'] }),
  toggleGroup({ variant: 'ghost', label: 'Ghost', value: 'b', items: ['a', 'b', 'c'] }),
)
```

## Disabled items

```javascript
toggleGroup({
  label: 'Renderer',
  value: 'static',
  items: [
    { value: 'static', label: 'Static' },
    { value: 'islands', label: 'Islands' },
    { value: 'ssr', label: 'SSR', disabled: true },
  ],
})
```

## In a toolbar

```javascript
stack({ direction: 'row', gap: 'md', wrap: true, align: 'center' },
  toggleGroup({ label: 'Alignment', value: 'Left', size: 'sm', items: ['Left', 'Center', 'Right'] }),
  divider({ orientation: 'vertical' }),
  toggleGroup({ label: 'Style', value: ['Bold'], size: 'sm', items: ['Bold', 'Italic'] }),
)
```

## When to use something else

If the choice is submitted with a form, use `choiceGroup()` — real radios, no script needed. If each segment is a page, prefer the link form above. A toggle group is for a choice the page itself acts on.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `Array` | `[]` | Strings, or { value, label, href, disabled } objects. |
| `value` | `string \| number \| Array` | — | Which item is on. An array when several can be. |
| `label` | `string` | — | Accessible name for the group. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Applied to every item. |
| `variant` | `'outline' \| 'ghost' \| 'soft'` | `'outline'` | How an item that is off looks. |