Button Group

updated

Buttons that decided to move in together.

Demo

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.

Vertical button group

Sizes

Sizes

Nested

A group of groups spaces its children apart, so related sets stay joined and read as one toolbar.

Nested button groups

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".

With separators

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.

With an input
https://

Split button

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.

Connected button group

API Reference

Data attributes

data-slotAttributesDescription
button-groupdata-orientationThe group.
button-group-separatordata-orientationA 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.

Changelog

  1. registry 0.22.0

    ea2717b — In a ToggleGroup (or a ButtonGroup of toggles) whose activeVariant is outline or subtle, pressed neighbours share one edge instead of drawing two side by side: Toggle and ToggleGroupItem carry data-active-variant, and the group overlaps them by that edge as it does for an outline variant.

  2. registry 0.10.0

    0a9aa94 — DropdownMenu and ContextMenu are removed: Menu covers both, opening on click from the element it sits in or from a MenuTrigger, and with context-menu on right-click and long-press. It has the same parts (MenuItem, MenuCheckboxItem, MenuRadioGroup, MenuRadioItem, MenuLabel, MenuSeparator, MenuShortcut, MenuGroup, MenuSub, MenuSubTrigger, MenuSubContent), sizes and styles, so moving over means renaming the parts and replacing DropdownMenuTrigger/ContextMenuTrigger and the content part with a Menu inside the element that opens it; align="end" becomes anchor="bottom end" self="top end". Copies already in a project keep working. The Breadcrumb, ButtonGroup, DrawerMenu and overlay examples use Menu.

  3. registry 0.8.0

    74436ba — ButtonGroupSeparator keeps its one-pixel width but no longer fills it with bg-input, so it parts the buttons with a gap rather than a line.

  4. registry 0.5.0

    d290041 — Add Toggle and ToggleGroup. Toggle is a two-state button with Button's variants, colours and sizes, styled when on by activeVariant and activeColor; ToggleGroup joins toggles like a ButtonGroup, with single or multiple selection and arrow-key navigation. The core colour rules also match [data-state="on"][data-active-color], so an on toggle reads its active colour.

  5. core 0.4.0

    d290041 — Add Toggle and ToggleGroup. Toggle is a two-state button with Button's variants, colours and sizes, styled when on by activeVariant and activeColor; ToggleGroup joins toggles like a ButtonGroup, with single or multiple selection and arrow-key navigation. The core colour rules also match [data-state="on"][data-active-color], so an on toggle reads its active colour.