---
outline: deep
---

# Button group

Joins related `.l-button` elements into a single segmented control with shared borders.

**`<l-button-group>`** — Custom Element (no Shadow DOM)

```html
<l-button-group label="Alignment">
  <button class="l-button">Left</button>
  <button class="l-button">Center</button>
  <button class="l-button">Right</button>
</l-button-group>
```

## Options

### Label

Add `label` to give the group an accessible name announced by screen readers.

```html
<l-button-group label="Alignment">
  <button class="l-button">Left</button>
  <button class="l-button">Center</button>
  <button class="l-button">Right</button>
</l-button-group>
```

### Orientation

Add `orientation="vertical"` to stack the buttons.

```html
<l-button-group
  label="Alignment"
  orientation="vertical"
>
  <button class="l-button">Left</button>
  <button class="l-button">Center</button>
  <button class="l-button">Right</button>
</l-button-group>
```

### Sizes

Set `data-size` on every button so the group stays even.

```html
<l-button-group label="Pagination">
  <button
    class="l-button"
    data-size="lg"
  >
    Previous
  </button>
  <button
    class="l-button"
    data-size="lg"
  >
    Next
  </button>
</l-button-group>
```

## Examples

### Icon toolbar

Group icon-only buttons into a compact toolbar.

```html
<l-button-group label="Text formatting">
  <button
    class="l-button"
    aria-label="Bold"
  >
    <iconify-icon icon="lucide:bold"></iconify-icon>
  </button>
  <button
    class="l-button"
    aria-label="Italic"
  >
    <iconify-icon icon="lucide:italic"></iconify-icon>
  </button>
  <button
    class="l-button"
    aria-label="Underline"
  >
    <iconify-icon icon="lucide:underline"></iconify-icon>
  </button>
</l-button-group>
```

### Split button

Pair a primary action with an `<l-dropdown>` of related actions. The group rounds the corners of the dropdown trigger automatically.

```html
<l-button-group label="Save options">
  <button
    class="l-button"
    data-variant="primary"
  >
    Save
  </button>
  <l-dropdown>
    <button
      slot="trigger"
      class="l-button"
      data-variant="primary"
      data-icon-only
      aria-label="More save options"
    >
      <iconify-icon icon="lucide:chevron-down"></iconify-icon>
    </button>
    <l-dropdown-item value="draft">Save as draft</l-dropdown-item>
    <l-dropdown-item value="template">Save as template</l-dropdown-item>
  </l-dropdown>
</l-button-group>
```

## Accessibility

### Criteria

- **Role** — Host gets `role="group"` to expose the buttons as a set
- **Accessible name** — `label` sets `aria-label` so assistive tech announces the group purpose
- **Orientation** — `aria-orientation` reflects the `orientation` attribute
- **Focus order** — Each button is an independent `Tab` stop; the focus ring is raised above neighbours so it is never clipped
- **Icon-only buttons** — Each icon-only button needs its own `aria-label`

### Rules

- Always add a `label` describing the group purpose
- Children must be native `<button class="l-button">` elements (optionally wrapped in `l-dropdown` for split buttons)
- Give each icon-only button its own `aria-label`

### Keyboard interactions

- `Tab` — Moves focus to the next button in the group
- `Shift + Tab` — Moves focus to the previous button
- `Enter` — Activates the focused button
- `Space` — Activates the focused button

## API reference

### Importing

```js
import 'luxen-ui/button-group';
```

```css
@import 'luxen-ui/css/button-group';
```

### Attributes & Properties

- **label**: `string | undefined` — Accessible label announced for the group. Not displayed on screen.
- **orientation**: `ButtonGroupOrientation` (default: `'horizontal'`) — Layout direction of the buttons. Visual only (drives the CSS via the
reflected attribute): ARIA 1.2 does not allow `aria-orientation` on
`role="group"`, so no ARIA attribute is set.