---

## ButtonGroup
Groups related buttons with shared styling, layout, and optional selection behaviour.
Supports single-select (radio), multi-select (checkbox), or no selection.

**Import:** `import { ButtonGroup } from '@urbicon-ui/blocks';`

### Examples
```svelte
<ButtonGroup selection="single" bind:value={selectedView}>
  <Button value="list">List</Button>
  <Button value="grid">Grid</Button>
</ButtonGroup>
```

```svelte
<ButtonGroup
  selection="multiple"
  bind:value={selectedFormats}
  connected
  size="sm"
  variant="outlined"
>
  <Button value="bold">B</Button>
  <Button value="italic">I</Button>
  <Button value="underline">U</Button>
</ButtonGroup>
```

### Variants
- connected: false, true (default: true)
- disabled: true (default: false)
- orientation: horizontal, vertical (default: horizontal)
- tier: commit, modify (default: commit)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ariaLabel | `string` | no |  | Accessible label for the group (prefer this over `aria-label` for correct HTML attribute). |
| ariaLabelledBy | `string` | no |  | ID of the element that labels the group. |
| children | `Snippet` | no |  | Button children to group. |
| class | `string` | no |  | Extra classes merged onto the root element. |
| connected | `boolean` | no |  | Visually connect buttons (overlapping borders, shared rounding). When `false`, buttons are spaced with a small gap. |
| disabled | `boolean` | no |  | Disable the entire group and all child Buttons. |
| intent | `ComponentIntent` | no |  | Semantic colour propagated to child Buttons. |
| mint | `MintProp` | no |  | Micro-interaction preset propagated to child Buttons. |
| onSelectionChange | `(value: ButtonGroupValue, selectedValues: string[]) => void` | no |  | Fired when selection changes. Receives the new value and an array of all selected values. |
| orientation | `ButtonGroupOrientation` | no |  | Orientation property for the ButtonGroup component |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ ButtonGroup: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| selection | `ButtonGroupSelection` | no |  | Selection mode. `"single"` = radio-group, `"multiple"` = checkbox-group, `"none"` = no selection. |
| size | `ComponentSize` | no |  | Size propagated to child Buttons (unless a Button sets its own). |
| slotClasses | `Partial<Record<ButtonGroupSlots, string>>` | no |  | Per-slot class overrides. Slots: base |
| tier | `InteractiveTier` | no |  | Semantic radius tier propagated to child Buttons. `commit` (default) → pill caps for the group; `modify` → soft caps. Inherits from a wrapping Toolbar via TierContext when not set explicitly. |
| unstyled | `boolean` | no |  | Remove all default tv classes. |
| value | `ButtonGroupValue` | no |  | Current selection value. Bind with `bind:value` for two-way sync. String for single, string[] for multiple. |
| variant | `ButtonVariants['variant']` | no |  | Visual weight propagated to child Buttons. |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)