# `src/components/button-group/ButtonGroup.ts`:

## class: `ButtonGroup`, `btu-button-group`

### Superclass

| Name         | Module | Package |
| ------------ | ------ | ------- |
| `LitElement` |        | lit     |

### Mixins

| Name                   | Module                            | Package |
| ---------------------- | --------------------------------- | ------- |
| `RovingTabindexMixin`  | /src/util/RovingTabindexMixin.js  |         |
| `ComponentStatesMixin` | /src/util/ComponentStatesMixin.js |         |
| `EventEmitterMixin`    | /src/util/EventEmitterMixin.js    |         |
| `ReadyMixin`           | /src/util/ReadyMixin.js           |         |

### Static Fields

| Name      | Privacy | Type | Default | Description | Inherited From |
| --------- | ------- | ---- | ------- | ----------- | -------------- |
| `tagName` |         |      |         |             |                |

### Fields

| Name          | Privacy | Type                               | Default        | Description                                                                                                                                                         | Inherited From |
| ------------- | ------- | ---------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `label`       |         | `string`                           | `''`           | Accessible name for the group, announced by assistive devices via aria-label.                                                                                       |                |
| `orientation` |         | `'horizontal' \| 'vertical'`       | `'horizontal'` | Layout direction of the buttons.                                                                                                                                    |                |
| `variant`     |         | `'connected' \| 'spaced'`          | `'connected'`  | \`connected\` collapses shared borders for a joined appearance.&#xA;\`spaced\` renders buttons with a gap.                                                          |                |
| `size`        |         | `'sm' \| 'md' \| 'lg'`             | `'md'`         | Propagates a uniform size to all child buttons.                                                                                                                     |                |
| `disabled`    |         | `boolean`                          | `false`        | When true, disables all child buttons as a group.                                                                                                                   |                |
| `selection`   |         | `'none' \| 'single' \| 'multiple'` | `'none'`       | Enables toggle/selection behavior.&#xA;\`single\` allows one active button; \`multiple\` allows many.                                                               |                |
| `value`       |         | `string`                           | `''`           | Reflects the currently selected button value(s).&#xA;For \`single\`, the value of the active button.&#xA;For \`multiple\`, a comma-delimited list of active values. |                |
| `name`        |         | `string`                           | `''`           | When set, creates hidden input(s) for native form participation.                                                                                                    |                |

### Methods

| Name   | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
| ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
| `emit` |         | Dispatches a type-safe CustomEvent with standardized configuration.&#xA;&#xA;All events are configured with:&#xA;- bubbles: true (event propagates up the DOM tree)&#xA;- cancelable: false (event cannot be cancelled)&#xA;- composed: true (event crosses shadow DOM boundaries) | `type: K, detail: UnpackCustomEvent<CustomEventMap[K]>` | `boolean` | EventEmitterMixin |

### Events

| Name                      | Type                                       | Description                                               | Inherited From |
| ------------------------- | ------------------------------------------ | --------------------------------------------------------- | -------------- |
| `btu-button-group-ready`  | `CustomEvent`                              | Fired after first render and initialization               |                |
| `btu-button-group-change` | `CustomEvent<{value: string}>`             | Fired when selection changes (single/multiple modes only) |                |
| `btu-icon-button-click`   | `CustomEvent<{name: string \| undefined}>` | Bubbles from child btu-icon-button elements when clicked  |                |

### Attributes

| Name          | Field       | Inherited From |
| ------------- | ----------- | -------------- |
| `label`       | label       |                |
| `orientation` | orientation |                |
| `variant`     | variant     |                |
| `size`        | size        |                |
| `disabled`    | disabled    |                |
| `selection`   | selection   |                |
| `value`       | value       |                |
| `name`        | name        |                |

### CSS Properties

| Name                               | Default | Description                                                                                                                                                                                                                               |
| ---------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--button-group-gap`               |         | Space between buttons when variant="spaced" (default: spacing.sm)                                                                                                                                                                         |
| `--button-group-border-radius`     |         | Corner radius of outer edges when variant="connected" (default: 0.5rem)                                                                                                                                                                   |
| `--button-group-border-color`      |         | Internal divider color between connected buttons (default: gray-300)                                                                                                                                                                      |
| `--button-group-selection-bg`      |         | Background of a toggled/selected child (default: child's --button-tint-subtle)                                                                                                                                                            |
| `--button-group-selection-color`   |         | Text/icon color of a toggled/selected child (default: child's --button-tint-strong)                                                                                                                                                       |
| `--button-group-shimmer-highlight` |         | Highlight color of the selection shimmer effect (default: child's --button-tint-highlight) Reads the following CSS custom properties from each child button (set by the button plugin per color variant — see tailwind-plugin-button.ts): |
| `--button-tint-subtle`             |         | Subtle tint of the child button's color family (read-only here)                                                                                                                                                                           |
| `--button-tint-strong`             |         | Strong tint of the child button's color family (read-only here)                                                                                                                                                                           |
| `--button-tint-highlight`          |         | Highlight tint of the child button's color family (read-only here)                                                                                                                                                                        |

### Slots

| Name  | Description                                                                                                                                                                                                                                                                                                          |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|       | One or more \`\<button class="btu-button …">\` or \`\<btu-icon-button>\` elements to display in the group. The \`connected\` variant rounds the outer corners on the real \`\<button>\`, so anchors styled as \`.btu-button\` slotted directly will not get rounded corners. Use \`\<button>\` for grouped controls. |
| `end` | Pushes the child to the end of the group via auto-margin (vertical: bottom, horizontal: right)                                                                                                                                                                                                                       |

<hr/>

## Exports

| Kind                        | Name               | Declaration | Module                                     | Package |
| --------------------------- | ------------------ | ----------- | ------------------------------------------ | ------- |
| `js`                        | `default`          | ButtonGroup | src/components/button-group/ButtonGroup.ts |         |
| `custom-element-definition` | `btu-button-group` | ButtonGroup | src/components/button-group/ButtonGroup.ts |         |
