# Button group

> Connected actions joined into one surface: hairline dividers, a gliding hover highlight, and responsive auto-collapsing labels.

Related actions fused into a single hairline capsule with internal dividing hairlines. A soft highlight glides between segments under cursor hover or keyboard navigation, dividers quietly step aside next to active items, and labels automatically collapse to icons on narrow screens.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/button-group.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: none
- Hairline UI components it needs (the CLI installs them too): `ui-interaction-motion`
- Docs and live preview: https://hairlineui.com/ui/button-group
- Registry item (source): https://hairlineui.com/r/button-group.json

## Usage

```tsx
import { ButtonGroup } from "@/components/ui/button-group";
import { Grid, List, Columns } from "lucide-react";

<ButtonGroup
  items={[
    { id: "grid", label: "Grid", icon: <Grid size={14} />, active: true },
    { id: "list", label: "List", icon: <List size={14} /> },
    { id: "columns", label: "Columns", icon: <Columns size={14} /> },
  ]}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `ButtonGroupItem[]` | – | Array of action items in the group. |
| `variant` | `"outline" \| "solid"` | `"outline"` | Outline with hairline border or solid dark fill. |
| `size` | `"sm" \| "md"` | `"md"` | Control height and typography. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction. |
| `collapseLabels` | `boolean` | `true` | Automatically collapse labels to icons when space overflows. |

## States

- **idle**: Resting capsule with hairline dividers between segments.
- **hovered**: Gliding highlight pill positioned under active segment; neighboring dividers fade.
- **focused**: Keyboard focus ring and highlight navigating with arrow keys.
- **compact**: Collapsed labels showing icons on narrow containers.

## What it handles

Multiple buttons side by side usually create cramped margins and multiple clashing borders. This component joins actions into one continuous hairline surface with smooth kinetic focus gliding.

- **Gliding highlight**: A soft pill highlight glides seamlessly between segments on hover or arrow-key focus.
- **Quiet dividers**: Internal hairline dividers fade out beside the active segment so the highlight reads as a clean shape.
- **Auto-collapsing labels**: When container space is constrained, text labels collapse into icons automatically while preserving full accessibility and titles.
- **Horizontal & vertical**: Supports both horizontal toolbars and vertical sidebar action bars.

## Replaces

disconnected buttons, separate toolbar items, clashing margins, manual mobile icon swapping

## Where it fits

- **Editor toolbars**: Text alignment, formatting, and view toggle controls.
- **Segmented view switches**: Switching between Grid, List, and Table layouts.
- **Responsive header controls**: Actions that collapse gracefully on mobile devices.

## Notes

- No external animation libraries: uses CSS transitions and native layout geometry.
- Full keyboard accessibility: navigate with Arrow keys, Home, and End.

License: MIT (https://hairlineui.com/license#components)