Button Group

Groups related buttons into a single attached control, with optional separators.

import { ArchiveIcon, ForwardIcon, ReplyIcon } from 'lucide-react'
import { Button } from '@/components/ui/button'
import { ButtonGroup } from '@/components/ui/button-group'

export function ButtonGroupDemo() {
  return (
    <ButtonGroup aria-label="Message actions">
      <Button variant="outline">
        <ReplyIcon data-icon="inline-start" />
        Reply
      </Button>
      <Button variant="outline">
        <ForwardIcon data-icon="inline-start" />
        Forward
      </Button>
      <Button variant="outline" size="icon" aria-label="Archive message">
        <ArchiveIcon />
      </Button>
    </ButtonGroup>
  )
}

Installation

pnpm dlx shadcn@latest add https://rdf.dev.360online.com/r/button-group.json

Installs to @/components/ui/button-group.

Manual installation

Install the dependencies:

pnpm add @base-ui/react@^1.8.0 class-variance-authority@^0.7.1

Add the components it builds on: separator.

Copy the source into your project:

components/ui/button-group.tsx

import { mergeProps } from '@base-ui/react/merge-props'
import { useRender } from '@base-ui/react/use-render'
import { cva, type VariantProps } from 'class-variance-authority'
import { Separator } from '@/components/ui/separator'
import { cn } from '@/lib/utils'

// A filled button paints inside its transparent border (bg-clip-padding), which leaves it a pixel short beside outlined
// buttons in a group; bg-clip-border lets it fill to the group's edge
const buttonGroupVariants = cva(
	"group/button-group flex w-fit items-stretch [&>[data-variant]]:bg-clip-border *:focus-visible:relative *:focus-visible:z-10 has-[>[data-slot=button-group]]:gap-2 has-[select[aria-hidden=true]:last-child]:[&>[data-slot=select-trigger]:last-of-type]:rounded-r-lg [&>[data-slot=select-trigger]:not([class*='w-'])]:w-fit [&>input]:flex-1",
	{
		variants: {
			orientation: {
				horizontal:
					'*:data-slot:rounded-r-none [&>[data-slot]:not(:has(~[data-slot]))]:rounded-r-lg! [&>[data-slot]~[data-slot]]:rounded-l-none [&>[data-slot]~[data-slot]]:border-l-0',
				vertical:
					'flex-col *:data-slot:rounded-b-none [&>[data-slot]:not(:has(~[data-slot]))]:rounded-b-lg! [&>[data-slot]~[data-slot]]:rounded-t-none [&>[data-slot]~[data-slot]]:border-t-0',
			},
		},
		defaultVariants: {
			orientation: 'horizontal',
		},
	},
)

function ButtonGroup({
	className,
	orientation,
	...props
}: React.ComponentProps<'div'> & VariantProps<typeof buttonGroupVariants>) {
	return (
		<div
			role="group"
			data-slot="button-group"
			data-orientation={orientation}
			className={cn(buttonGroupVariants({ orientation }), className)}
			{...props}
		/>
	)
}

function ButtonGroupText({ className, render, ...props }: useRender.ComponentProps<'div'>) {
	return useRender({
		defaultTagName: 'div',
		props: mergeProps<'div'>(
			{
				className: cn(
					"flex items-center gap-2 rounded-lg border bg-muted px-2.5 text-sm font-medium [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
					className,
				),
			},
			props,
		),
		render,
		state: {
			slot: 'button-group-text',
		},
	})
}

function ButtonGroupSeparator({
	className,
	orientation = 'vertical',
	...props
}: React.ComponentProps<typeof Separator>) {
	return (
		<Separator
			data-slot="button-group-separator"
			orientation={orientation}
			className={cn(
				'relative self-stretch bg-input data-horizontal:mx-px data-horizontal:w-auto data-vertical:my-px data-vertical:h-auto',
				className,
			)}
			{...props}
		/>
	)
}

export { ButtonGroup, ButtonGroupSeparator, ButtonGroupText, buttonGroupVariants }

Groups related buttons — or an input together with buttons — into one visual control. Adjacent borders and corner radii are merged, and nested groups are spaced apart.

Features

Horizontal and vertical orientation
ButtonGroupSeparator for split buttons
ButtonGroupText for static prefixes/suffixes
ButtonGroupText supports the render prop (e.g. to render a Label)
Nested ButtonGroups are spaced apart automatically
Works with any Button variant and size (including xs and icon sizes), Input, or Select
buttonGroupVariants is exported for reuse

Usage

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

<ButtonGroup aria-label="Message actions">
  <Button variant="outline">Reply</Button>
  <Button variant="outline">Forward</Button>
  <Button variant="outline">Archive</Button>
</ButtonGroup>

// Split button
<ButtonGroup>
  <Button>Send decision</Button>
  <ButtonGroupSeparator />
  <Button size="icon" aria-label="More ways to send">
    <ChevronDown />
  </Button>
</ButtonGroup>

Examples

Default

Actions on a message in the case inbox. Give the group an aria-label when its purpose isn’t obvious from the buttons.

import { ArchiveIcon, ForwardIcon, ReplyIcon } from 'lucide-react'
import { Button } from '@/components/ui/button'
import { ButtonGroup } from '@/components/ui/button-group'

export function ButtonGroupDemo() {
  return (
    <ButtonGroup aria-label="Message actions">
      <Button variant="outline">
        <ReplyIcon data-icon="inline-start" />
        Reply
      </Button>
      <Button variant="outline">
        <ForwardIcon data-icon="inline-start" />
        Forward
      </Button>
      <Button variant="outline" size="icon" aria-label="Archive message">
        <ArchiveIcon />
      </Button>
    </ButtonGroup>
  )
}

Sizes

Buttons keep their own size inside a group; use matching text and icon sizes.

import { ChevronDownIcon, FileDownIcon } from 'lucide-react'
import { Button } from '@/components/ui/button'
import { ButtonGroup } from '@/components/ui/button-group'

export function ButtonGroupSizes() {
  return (
    <div className="flex flex-col items-start gap-4">
      {(
        [
          ['xs', 'icon-xs'],
          ['sm', 'icon-sm'],
          ['default', 'icon'],
          ['lg', 'icon-lg'],
        ] as const
      ).map(([size, iconSize]) => (
        <ButtonGroup key={size}>
          <Button variant="outline" size={size}>
            <FileDownIcon data-icon="inline-start" />
            Export case list
          </Button>
          <Button variant="outline" size={iconSize} aria-label="Choose export format">
            <ChevronDownIcon />
          </Button>
        </ButtonGroup>
      ))}
    </div>
  )
}

Vertical

orientation="vertical" stacks the buttons, here as zoom controls on a property map.

import { LocateFixedIcon, MinusIcon, PlusIcon } from 'lucide-react'
import { Button } from '@/components/ui/button'
import { ButtonGroup } from '@/components/ui/button-group'

export function ButtonGroupVertical() {
  return (
    <div className="relative h-56 w-sm max-w-full overflow-hidden rounded-lg border bg-muted/50">
      <div className="absolute inset-0 bg-[linear-gradient(var(--border)_1px,transparent_1px),linear-gradient(90deg,var(--border)_1px,transparent_1px)] bg-size-[28px_28px]" />
      <span className="absolute bottom-3 left-3 rounded-md bg-background/90 px-2 py-1 text-xs shadow-sm">
        Detailed plan DP 1987-03
      </span>
      <ButtonGroup orientation="vertical" aria-label="Map controls" className="absolute top-3 right-3 bg-background">
        <Button variant="outline" size="icon-sm" aria-label="Zoom in">
          <PlusIcon />
        </Button>
        <Button variant="outline" size="icon-sm" aria-label="Zoom out">
          <MinusIcon />
        </Button>
        <Button variant="outline" size="icon-sm" aria-label="Show my location">
          <LocateFixedIcon />
        </Button>
      </ButtonGroup>
    </div>
  )
}

With separator

A split button: the main action plus a dropdown with alternatives, divided by ButtonGroupSeparator.

import { ChevronDownIcon, ClockIcon, SaveIcon, SendIcon } from 'lucide-react'
import { Button } from '@/components/ui/button'
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from '@/components/ui/dropdown-menu'
import { ButtonGroup, ButtonGroupSeparator } from '@/components/ui/button-group'

export function ButtonGroupWithSeparator() {
  return (
    <ButtonGroup>
      <Button>
        <SendIcon data-icon="inline-start" />
        Send decision
      </Button>
      <ButtonGroupSeparator className="bg-primary-foreground/30" />
      <DropdownMenu>
        <DropdownMenuTrigger render={<Button size="icon" aria-label="More ways to send" />}>
          <ChevronDownIcon />
        </DropdownMenuTrigger>
        <DropdownMenuContent align="end">
          <DropdownMenuItem>
            <SendIcon />
            Send and close case
          </DropdownMenuItem>
          <DropdownMenuItem>
            <ClockIcon />
            Schedule sending
          </DropdownMenuItem>
          <DropdownMenuSeparator />
          <DropdownMenuItem>
            <SaveIcon />
            Save as draft
          </DropdownMenuItem>
        </DropdownMenuContent>
      </DropdownMenu>
    </ButtonGroup>
  )
}

With text

ButtonGroupText with render={<Label />} renders a Label as a prefix for an input.

import { SearchIcon } from 'lucide-react'
import * as React from 'react'
import { Button } from '@/components/ui/button'
import { Input } from '@/components/ui/input'
import { Label } from '@/components/ui/label'
import { ButtonGroup, ButtonGroupText } from '@/components/ui/button-group'

export function ButtonGroupWithText() {
  const id = React.useId()
  return (
    <ButtonGroup className="w-full max-w-sm">
      <ButtonGroupText render={<Label htmlFor={`${id}-case`} />}>Case no.</ButtonGroupText>
      <Input id={`${id}-case`} placeholder="2026-04812" inputMode="numeric" />
      <Button variant="outline" size="icon" aria-label="Find case">
        <SearchIcon />
      </Button>
    </ButtonGroup>
  )
}

Stepper

A number stepper built from two icon buttons and ButtonGroupText. The buttons use focusableWhenDisabled, so keyboard focus stays on a button when it reaches the limit and becomes disabled.

import { MinusIcon, PlusIcon } from 'lucide-react'
import * as React from 'react'
import { Button } from '@/components/ui/button'
import { ButtonGroup, ButtonGroupText } from '@/components/ui/button-group'

export function ButtonGroupStepper() {
  const id = React.useId()
  const [count, setCount] = React.useState(2)
  return (
    <div className="flex w-full max-w-sm items-center justify-between gap-4 rounded-lg border p-4">
      <div className="flex flex-col">
        <span id={id} className="text-sm font-medium">
          Children in the household
        </span>
        <span className="text-sm text-muted-foreground">Affects the preschool fee</span>
      </div>
      <ButtonGroup aria-labelledby={id}>
        <Button
          variant="outline"
          size="icon"
          aria-label="Fewer children"
          disabled={count <= 1}
          focusableWhenDisabled
          onClick={() => setCount((value) => value - 1)}
        >
          <MinusIcon />
        </Button>
        <ButtonGroupText className="w-10 justify-center bg-background tabular-nums" aria-live="polite">
          {count}
        </ButtonGroupText>
        <Button
          variant="outline"
          size="icon"
          aria-label="More children"
          disabled={count >= 9}
          focusableWhenDisabled
          onClick={() => setCount((value) => value + 1)}
        >
          <PlusIcon />
        </Button>
      </ButtonGroup>
    </div>
  )
}

Nested groups

Nested groups are spaced apart automatically, like the week navigation and Today button in a calendar header.

import { ChevronLeftIcon, ChevronRightIcon } from 'lucide-react'
import { Button } from '@/components/ui/button'
import { ButtonGroup } from '@/components/ui/button-group'

export function ButtonGroupNested() {
  return (
    <div className="flex w-full max-w-md items-center justify-between gap-4">
      <h3 className="text-sm font-medium">Week 16 · 13–19 April 2026</h3>
      <ButtonGroup aria-label="Calendar navigation">
        <ButtonGroup>
          <Button variant="outline" size="icon" aria-label="Previous week">
            <ChevronLeftIcon />
          </Button>
          <Button variant="outline" size="icon" aria-label="Next week">
            <ChevronRightIcon />
          </Button>
        </ButtonGroup>
        <ButtonGroup>
          <Button variant="outline">Today</Button>
        </ButtonGroup>
      </ButtonGroup>
    </div>
  )
}

Disabled

Disable a single button when that action isn't available.

import { ArchiveIcon, ForwardIcon, ReplyIcon } from 'lucide-react'
import { Button } from '@/components/ui/button'
import { ButtonGroup } from '@/components/ui/button-group'

export function ButtonGroupDisabled() {
  return (
    <ButtonGroup aria-label="Message actions">
      <Button variant="outline" disabled>
        <ReplyIcon data-icon="inline-start" />
        Reply
      </Button>
      <Button variant="outline">
        <ForwardIcon data-icon="inline-start" />
        Forward
      </Button>
      <Button variant="outline" size="icon" aria-label="Archive message">
        <ArchiveIcon />
      </Button>
    </ButtonGroup>
  )
}

Props

ButtonGroup - orientation?: 'horizontal' | 'vertical' (default 'horizontal'), renders role="group"
ButtonGroupText - render?: React.ReactElement, the element to render instead of a div
ButtonGroupSeparator - props of Separator; orientation defaults to 'vertical'

Button
Toggle Group
Input Group