Button Group
updatedButtons that decided to move in together.
Open Props in the corner of the example to try orientation.
Installation
Usage
<script setup lang="ts">
import { Button } from '@/components/ui/button'
import { ButtonGroup } from '@/components/ui/button-group'
</script>
<template>
<ButtonGroup aria-label="Text alignment">
<Button variant="outline" color="neutral">Left</Button>
<Button variant="outline" color="neutral">Center</Button>
<Button variant="outline" color="neutral">Right</Button>
</ButtonGroup>
</template>
The group only joins its children: it squares the corners where they meet and overlaps two neighbours that both have an edge by 1px, so the edges of outlined buttons, inputs and text meet in a single line. It passes nothing down, so each button keeps its own variant, color and size.
Examples
Orientation
orientation="vertical" stacks the children and joins them top to bottom.
Sizes
Nested
A group of groups spaces its children apart, so related sets stay joined and read as one toolbar.
Separator
Buttons without an edge need a divider to read as separate. ButtonGroupSeparator draws one the height of the group; in a vertical group, give it orientation="horizontal".
Text and inputs
ButtonGroupText puts a label, prefix or suffix inside the group, at the group's height. Inputs join like buttons: a text field between a prefix and a button reads as one control. With as-child, the text can be a label for the input.
Split button
Connected
Made with classes only. Buttons sit 2px apart, outer corners are fully round, and inner corners stay small (set them with --button-group-radius). The selected button (aria-pressed) rounds all its corners, with a smooth transition.
Why not rounded-full? If one corner has an infinite radius, the browser shrinks every corner of the box, and the small inner ones disappear. So the outer radius is half the button's height.
API Reference
ButtonGroup
class is also accepted and merged over the group's classes with tailwind-merge. --button-group-radius sets the radius of the corners where children meet, 0px by default.
| Prop | Default | Type and description |
|---|---|---|
| orientation | "horizontal" | NonNullable<"horizontal" | "vertical" | null | undefined>Lays the children in a row or a column and squares the corners where they meet. |
| Slot | Scope and description |
|---|---|
| default | {}Buttons, nested groups and separators. Nothing is passed to them, so each button keeps its own variant and size. |
ButtonGroupSeparator
| Prop | Default | Type and description |
|---|---|---|
| orientation | "vertical" | "vertical" | "horizontal"
|
ButtonGroupText
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging the text's attributes and classes onto it — a |
| as | "div" | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The text and an optional icon. |
class is also accepted and merged over the group's classes with tailwind-merge. --button-group-radius sets the radius of the corners where children meet, 0px by default.
Props
- orientation
"horizontal" NonNullable<"horizontal" | "vertical" | null | undefined>Lays the children in a row or a column and squares the corners where they meet.
Slots
- default
{}Buttons, nested groups and separators. Nothing is passed to them, so each button keeps its own variant and size.
Props
- orientation
"vertical" "vertical" | "horizontal"verticalbetween buttons in a row,horizontalin a vertical group.
Props
- asChild
booleanRender the single child instead of a wrapper, merging the text's attributes and classes onto it — alabel, for instance.- as
"div" AsTag | ComponentThe element or component to render.
Slots
- default
{}The text and an optional icon.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| button-group | data-orientation | The group. |
| button-group-separator | data-orientation | A divider between two children. |
| button-group-text | — | Text inside the group, or your own element under as-child. |
Accessibility
The group renders role="group"; give it an aria-label that names what its buttons do together. When the buttons pick one option, as in the connected example, mark the chosen one with aria-pressed.