# `PUI.ButtonGroup`

A container that groups related buttons together with consistent styling.

## Basic Usage

    <.button_group>
      <.button variant="outline">Button 1</.button>
      <.button variant="outline">Button 2</.button>
    </.button_group>

## With Separator

Visually divide buttons within a group. Separators are most useful with
non-outline variants since outline buttons already have visible borders.

    <.button_group>
      <.button variant="secondary">Copy</.button>
      <.button_group_separator />
      <.button variant="secondary">Paste</.button>
    </.button_group>

## With Text

Add a text label within the group:

    <.button_group>
      <.button_group_text>Label</.button_group_text>
      <.button variant="outline">Action</.button>
    </.button_group>

## Vertical Orientation

    <.button_group orientation="vertical">
      <.button variant="outline" size="icon">
        <.icon name="hero-plus" />
      </.button>
      <.button variant="outline" size="icon">
        <.icon name="hero-minus" />
      </.button>
    </.button_group>

## Nested Groups

Nest button groups to create complex layouts with spacing between sub-groups:

    <.button_group>
      <.button_group>
        <.button variant="outline" size="icon">
          <.icon name="hero-plus" />
        </.button>
      </.button_group>
      <.button_group>
        <.input placeholder="Search..." />
      </.button_group>
    </.button_group>

## Split Button

Create a split button by combining a button with a separator and an icon button:

    <.button_group>
      <.button variant="secondary">Send</.button>
      <.button_group_separator />
      <.button variant="secondary" size="icon">
        <.icon name="hero-chevron-down" />
      </.button>
    </.button_group>

## Attributes

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `orientation` | `string` | `"horizontal"` | Layout direction: `"horizontal"` or `"vertical"` |
| `class` | `string` | `""` | Additional CSS classes |
| `rest` | `global` | - | HTML attributes including `aria-label` |

## Slots

| Slot | Description |
|------|-------------|
| `inner_block` | Group content (required) — typically buttons, separators, or text |

## Accessibility

- The container has `role="group"` for assistive technologies.
- Use `aria-label` or `aria-labelledby` to describe the group's purpose.
- Use `Tab` to navigate between buttons in the group.

# `button_group`

## Attributes

* `orientation` (`:string`) - Defaults to `"horizontal"`. Must be one of `"horizontal"`, or `"vertical"`.
* `class` (`:string`) - Defaults to `""`.
* Global attributes are accepted.
## Slots

* `inner_block` (required)

# `button_group_separator`

A visual separator between buttons within a button group.

Use this to visually divide buttons in a group, especially with non-outline
variants. Outline buttons already have visible borders and typically don't
need a separator.

## Usage

    <.button_group>
      <.button variant="secondary">Copy</.button>
      <.button_group_separator />
      <.button variant="secondary">Paste</.button>
    </.button_group>

## Attributes

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `orientation` | `string` | `"horizontal"` | Separator direction: `"horizontal"` (vertical line) or `"vertical"` (horizontal line) |
| `class` | `string` | `""` | Additional CSS classes |

## Attributes

* `orientation` (`:string`) - Defaults to `"horizontal"`. Must be one of `"horizontal"`, or `"vertical"`.
* `class` (`:string`) - Defaults to `""`.

# `button_group_text`

Displays text content within a button group, typically used as a label.

## Usage

    <.button_group>
      <.button_group_text>Prefix</.button_group_text>
      <.button variant="outline">Action</.button>
    </.button_group>

## Attributes

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `class` | `string` | `""` | Additional CSS classes |

## Slots

| Slot | Description |
|------|-------------|
| `inner_block` | Text content (required) |

## Attributes

* `class` (`:string`) - Defaults to `""`.
## Slots

* `inner_block` (required)

---

*Consult [api-reference.md](api-reference.md) for complete listing*