Button Group

A container that groups related buttons with shared borders and outer corners only.

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
import { ArchiveIcon } from "@phosphor-icons/react/dist/csr/Archive"
import { ClockIcon } from "@phosphor-icons/react/dist/csr/Clock"
import { EnvelopeOpenIcon } from "@phosphor-icons/react/dist/csr/EnvelopeOpen"
import { TrashIcon } from "@phosphor-icons/react/dist/csr/Trash"

export default function ButtonGroupDemo() {
  return (
    <ButtonGroup aria-label="Message actions">
      <Button variant="outline" size="icon" aria-label="Archive">
        <ArchiveIcon aria-hidden="true" />
      </Button>
      <Button variant="outline" size="icon" aria-label="Mark as read">
        <EnvelopeOpenIcon aria-hidden="true" />
      </Button>
      <Button variant="outline" size="icon" aria-label="Snooze">
        <ClockIcon aria-hidden="true" />
      </Button>
      <Button variant="outline" size="icon" aria-label="Delete">
        <TrashIcon aria-hidden="true" />
      </Button>
    </ButtonGroup>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/button-group

Needs the arene setup first. Also adds Button.

Usage

import { Button } from "@/components/ui/button"
import { ButtonGroup, ButtonGroupSeparator, ButtonGroupText } from "@/components/ui/button-group"
<ButtonGroup aria-label="Message actions">
  <Button variant="outline">Archive</Button>
  <Button variant="outline">Report</Button>
  <Button variant="outline">Snooze</Button>
</ButtonGroup>

Give every group an aria-label or aria-labelledby. Without one, a screen reader announces the group with no name.

Use ButtonGroup for buttons that each perform an action. Buttons that toggle a shared state are a toggle group, which arene does not ship yet.

Orientation

Set orientation="vertical" to stack the members.

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
import { MinusIcon } from "@phosphor-icons/react/dist/csr/Minus"
import { PlusIcon } from "@phosphor-icons/react/dist/csr/Plus"

export default function ButtonGroupOrientation() {
  return (
    <ButtonGroup orientation="vertical" aria-label="Zoom">
      <Button variant="outline" size="icon" aria-label="Zoom in">
        <PlusIcon aria-hidden="true" />
      </Button>
      <Button variant="outline" size="icon" aria-label="Zoom out">
        <MinusIcon aria-hidden="true" />
      </Button>
    </ButtonGroup>
  )
}

Size

The group takes no size. Set it on each button, and give every member the same one.

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
import { VStack } from "@/components/ui/stack"

export default function ButtonGroupSize() {
  return (
    <VStack gap={4} align="start">
      <ButtonGroup aria-label="Small">
        <Button variant="outline" size="sm">
          Day
        </Button>
        <Button variant="outline" size="sm">
          Week
        </Button>
        <Button variant="outline" size="sm">
          Month
        </Button>
      </ButtonGroup>
      <ButtonGroup aria-label="Default">
        <Button variant="outline">Day</Button>
        <Button variant="outline">Week</Button>
        <Button variant="outline">Month</Button>
      </ButtonGroup>
      <ButtonGroup aria-label="Large">
        <Button variant="outline" size="lg">
          Day
        </Button>
        <Button variant="outline" size="lg">
          Week
        </Button>
        <Button variant="outline" size="lg">
          Month
        </Button>
      </ButtonGroup>
    </VStack>
  )
}

Side by side

Nesting a group inside another group does nothing. To place groups side by side, put them in an HStack and set the space between them with its gap.

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
import { HStack } from "@/components/ui/stack"
import { CaretLeftIcon } from "@phosphor-icons/react/dist/csr/CaretLeft"
import { CaretRightIcon } from "@phosphor-icons/react/dist/csr/CaretRight"

export default function ButtonGroupNested() {
  return (
    <HStack gap={2}>
      <ButtonGroup aria-label="Pages">
        <Button variant="outline">1</Button>
        <Button variant="outline">2</Button>
        <Button variant="outline">3</Button>
      </ButtonGroup>
      <ButtonGroup aria-label="Pagination">
        <Button variant="outline" size="icon" aria-label="Previous">
          <CaretLeftIcon aria-hidden="true" />
        </Button>
        <Button variant="outline" size="icon" aria-label="Next">
          <CaretRightIcon aria-hidden="true" />
        </Button>
      </ButtonGroup>
    </HStack>
  )
}

Separator

Use ButtonGroupSeparator between solid variants, which have no visible border of their own. It runs across the group's axis.

import { Button } from "@/components/ui/button"
import { ButtonGroup, ButtonGroupSeparator } from "@/components/ui/button-group"

export default function ButtonGroupSeparatorDemo() {
  return (
    <ButtonGroup aria-label="Text alignment">
      <Button variant="secondary">Left</Button>
      <ButtonGroupSeparator />
      <Button variant="secondary">Center</Button>
      <ButtonGroupSeparator />
      <Button variant="secondary">Right</Button>
    </ButtonGroup>
  )
}

Outline buttons already share their border, so a separator between them draws a second line. Use it with default, secondary and destructive.

Split button

Pair an action with a menu that offers the alternatives. The menu trigger renders a Button, so it joins the group like any other member.

import { Button } from "@/components/ui/button"
import { ButtonGroup, ButtonGroupSeparator } from "@/components/ui/button-group"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
import { CaretDownIcon } from "@phosphor-icons/react/dist/csr/CaretDown"

export default function ButtonGroupSplit() {
  return (
    <ButtonGroup aria-label="Merge">
      <Button variant="secondary">Merge pull request</Button>
      <ButtonGroupSeparator />
      <DropdownMenu>
        <DropdownMenuTrigger
          render={<Button variant="secondary" size="icon" aria-label="More merge options" />}
        >
          <CaretDownIcon aria-hidden="true" />
        </DropdownMenuTrigger>
        <DropdownMenuContent align="end">
          <DropdownMenuItem>Squash and merge</DropdownMenuItem>
          <DropdownMenuItem>Rebase and merge</DropdownMenuItem>
          <DropdownMenuItem>Create a merge commit</DropdownMenuItem>
        </DropdownMenuContent>
      </DropdownMenu>
    </ButtonGroup>
  )
}

With text

Use ButtonGroupText for an inert member, such as a label or a unit. Pass render to change the element.

npm install @base-ui/react
import { Button } from "@/components/ui/button"
import { ButtonGroup, ButtonGroupText } from "@/components/ui/button-group"
import { CopyIcon } from "@phosphor-icons/react/dist/csr/Copy"

export default function ButtonGroupTextDemo() {
  return (
    <ButtonGroup aria-label="Install command">
      <ButtonGroupText render={<code />}>npm install @base-ui/react</ButtonGroupText>
      <Button variant="outline" size="icon" aria-label="Copy command">
        <CopyIcon aria-hidden="true" />
      </Button>
    </ButtonGroup>
  )
}

API reference

Pass render to replace a part's element or compose it with another component.

ButtonGroup

Renders a div with role="group". A member is any child carrying a data-slot.

PropTypeDefault
orientation"horizontal" | "vertical""horizontal"
xstyleStyleXStyles—
classNamestring—

ButtonGroupSeparator

Wraps Base UI's Separator.

PropTypeDefault
orientation"horizontal" | "vertical"across the group's axis
xstyleStyleXStyles—
classNamestring—

ButtonGroupText

Renders a div through Base UI's useRender, so render swaps the element.

PropTypeDefault
renderReactElement—
xstyleStyleXStyles—
classNamestring—

Data attributes

AttributeOnEffect
data-slot="button-group"the groupTargets the group from a parent
data-orientationthe groupReflects the orientation prop
data-slot="button-group-separator"the separatorTargets the separator
data-slot="button-group-text"the textTargets the text member