# Button Group

> Group a series of buttons together on a single line with the button group.

Source: https://bootstrap-svelte.vercel.app/components/button-group — part of the Bootstrap Svelte documentation (index: https://bootstrap-svelte.vercel.app/llms.txt).

## Basic Example

Wrap a series of `Button` components with `ButtonGroup` component.

```html
<ButtonGroup>
    <Button colorVariant="primary">Left</Button>
    <Button colorVariant="primary">Middle</Button>
    <Button colorVariant="primary">Right</Button>
</ButtonGroup>
```

## Button Links

Use the `Button` component as a link by setting the `href` prop.

```html
<ButtonGroup>
    <Button aria-current="page" class="active" colorVariant="primary" href="#!">Active Link 1</Button>
    <Button colorVariant="primary" href="#!">Link 2</Button>
    <Button colorVariant="primary" href="#!">Link 3</Button>
</ButtonGroup>
```

## Mixed Styles

Mix and match button styles within a button group.

```html
<ButtonGroup>
    <Button colorVariant="danger">Left</Button>
    <Button colorVariant="secondary">Middle</Button>
    <Button colorVariant="success">Right</Button>
</ButtonGroup>
```

## Outlined Styles

Use outlined styles for a different look.

```html
<ButtonGroup>
    <Button colorVariant="outline-primary">Left</Button>
    <Button colorVariant="outline-primary">Middle</Button>
    <Button colorVariant="outline-primary">Right</Button>
</ButtonGroup>
```

## ButtonCheck Toggle Buttons

Use `ButtonCheck` to render Bootstrap toggle buttons powered by checkbox and radio inputs.

```html
<ButtonGroup ariaLabel="Toggle button group">
    <ButtonCheck colorVariant="outline-primary" id="toggle-check-1">Option 1</ButtonCheck>
    <ButtonCheck checked colorVariant="outline-primary" id="toggle-check-2">Option 2</ButtonCheck>
</ButtonGroup>

<ButtonGroup ariaLabel="Radio toggle button group">
    <ButtonCheck checked colorVariant="outline-secondary" id="toggle-radio-1" name="radio-toggles" type="radio">Active</ButtonCheck>
    <ButtonCheck colorVariant="outline-secondary" id="toggle-radio-2" name="radio-toggles" type="radio">Inactive</ButtonCheck>
</ButtonGroup>
```

## Button Toolbar

Combine sets of button groups into button toolbars for more complex components.

```html
<ButtonToolbar ariaLabel="Toolbar with button groups">
    <ButtonGroup class="me-2">
        <Button colorVariant="primary">1</Button>
        <Button colorVariant="primary">2</Button>
        <Button colorVariant="primary">3</Button>
        <Button colorVariant="primary">4</Button>
    </ButtonGroup>
    <ButtonGroup class="me-2">
        <Button colorVariant="secondary">5</Button>
        <Button colorVariant="secondary">6</Button>
        <Button colorVariant="secondary">7</Button>
    </ButtonGroup>
    <ButtonGroup>
        <Button colorVariant="info">8</Button>
        <Button colorVariant="info">9</Button>
    </ButtonGroup>
</ButtonToolbar>
```

## Sizing

Instead of applying button sizing props to every button in a group, just set the `size` prop on the `ButtonGroup`.

```html
<ButtonGroup size="lg">
    <Button colorVariant="outline-primary">Left</Button>
    <Button colorVariant="outline-primary">Middle</Button>
    <Button colorVariant="outline-primary">Right</Button>
</ButtonGroup>

<ButtonGroup>
    <Button colorVariant="outline-primary">Left</Button>
    <Button colorVariant="outline-primary">Middle</Button>
    <Button colorVariant="outline-primary">Right</Button>
</ButtonGroup>

<ButtonGroup size="sm">
    <Button colorVariant="outline-primary">Left</Button>
    <Button colorVariant="outline-primary">Middle</Button>
    <Button colorVariant="outline-primary">Right</Button>
</ButtonGroup>
```

## Nesting

Place a `ButtonGroup` within another `ButtonGroup` when you want dropdown menus mixed with regular buttons.

```html
<ButtonGroup>
    <Button colorVariant="primary">1</Button>
    <Button colorVariant="primary">2</Button>
    <ButtonGroup>
        <Button colorVariant="primary" id="btnGroupDrop1" class="dropdown-toggle">Dropdown</Button>
        <!-- Dropdown menu would be implemented here -->
    </ButtonGroup>
</ButtonGroup>
```

## Vertical Variation

Make a set of buttons appear vertically stacked rather than horizontally by adding the `vertical` prop.

```html
<ButtonGroup vertical>
    <Button colorVariant="primary">Button</Button>
    <Button colorVariant="primary">Button</Button>
    <Button colorVariant="primary">Button</Button>
    <Button colorVariant="primary">Button</Button>
</ButtonGroup>
```

## API Reference

### ButtonGroup Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | `'Button group [id]'` | ARIA label for the button group |
| `class` | `string` | `undefined` | Additional CSS classes to apply to the component. |
| `elementRef` | `HTMLElement \| null` | `null` | Reference to the DOM element |
| `id` | `string` | — | Unique identifier for the button. If not specified, it will be auto-generated. |
| `isVertical` | `boolean` | `false` | Makes the button group stack vertically |
| `size` | `string` | - | Sets the size for all buttons in the group. Values: 'sm', 'lg' |

### ButtonCheck Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `autocomplete` | `string` | `'off'` | Autocomplete behavior for the underlying input. |
| `checked` | `boolean` | `false` | Bindable checked state for checkbox inputs. |
| `class` | `string` | `undefined` | Additional CSS classes applied to the input element. |
| `colorVariant` | `ButtonColorVariant` | `undefined` | Bootstrap button variant for the label (for example, `primary` or `outline-primary`). |
| `elementRef` | `HTMLInputElement \| null` | `null` | Reference to the input element. |
| `group` | `string \| unknown[]` | `undefined` | Bindable group value for grouped radio or checkbox inputs. |
| `id` | `string` | `'btn-check-[id]'` | Input ID used by the label `for` attribute. |
| `labelClass` | `string` | `undefined` | Additional CSS classes applied to the label element. |
| `labelElementRef` | `HTMLLabelElement \| null` | `null` | Reference to the label element. |
| `type` | `'checkbox' \| 'radio'` | `'checkbox'` | Input type for the toggle button. |

### ButtonToolbar Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | `'Button toolbar [id]'` | ARIA label for the button group |
| `class` | `string` | `undefined` | Additional CSS classes to apply to the component. |
| `elementRef` | `HTMLElement \| null` | `null` | Reference to the DOM element |
| `id` | `string` | — | Unique identifier for the button. If not specified, it will be auto-generated. |

### CSS Classes

The component applies Bootstrap's button group classes:

- `btn-group` - Applied when isVertical prop is false
- `btn-group-vertical` - Applied when isVertical prop is true
- `btn-group-lg` - Applied when size="lg"
- `btn-group-sm` - Applied when size="sm"
- `btn-check` - Applied to the ButtonCheck input element.
- `btn` - Applied to the ButtonCheck label element.
- `btn-[variant]` - Applied to ButtonCheck labels when colorVariant is set.
- `btn-toolbar` - Applied when using the ButtonToolbar component.