Button Group

A container that groups related buttons together with consistent styling. Use it when you want to group buttons that perform an action — for buttons that toggle a state, reach for a toggle group instead.

Last updated August 7, 2026

CreditsUnchangedPublished

Copied from shadcn/ui.

Overview

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
 
export function ButtonGroupDemoExample() {
  return (
    <ButtonGroup>
      <Button variant="outline">Button 1</Button>
      <Button variant="outline">Button 2</Button>
    </ButtonGroup>
  )
}

Installation

$ npx shadcn@latest add https://ui.persian-labs.ir/r/button-group.json

Usage

import {
  ButtonGroup,
  ButtonGroupSeparator,
  ButtonGroupText,
} from "@/components/ui/button-group"
 
export function Example() {
  return (
    <ButtonGroup>
      <Button>Button 1</Button>
      <Button>Button 2</Button>
    </ButtonGroup>
  )
}

Orientation

Set the orientation prop to change the button group layout.

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
 
export function ButtonGroupOrientationExample() {
  return (
    <ButtonGroup orientation="vertical">
      <Button variant="outline">Button 1</Button>
      <Button variant="outline">Button 2</Button>
      <Button variant="outline">Button 3</Button>
    </ButtonGroup>
  )
}

Size

Control the size of buttons using the size prop on individual buttons.

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
 
export function ButtonGroupSizeExample() {
  return (
    <ButtonGroup>
      <Button variant="outline" size="sm">
        Button 1
      </Button>
      <Button variant="outline" size="sm">
        Button 2
      </Button>
    </ButtonGroup>
  )
}

Nested

Nest <ButtonGroup> components to create button groups with spacing.

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
 
export function ButtonGroupNestedExample() {
  return (
    <ButtonGroup>
      <ButtonGroup>
        <Button variant="outline">Button 1</Button>
        <Button variant="outline">Button 2</Button>
      </ButtonGroup>
      <ButtonGroup>
        <Button variant="outline">Button 3</Button>
      </ButtonGroup>
    </ButtonGroup>
  )
}

Separator

The ButtonGroupSeparator component visually divides buttons within a group. Buttons with the outline variant don't need one since they already have a border.

import { Button } from "@/components/ui/button"
import {
  ButtonGroup,
  ButtonGroupSeparator,
} from "@/components/ui/button-group"
 
export function ButtonGroupSeparatorExample() {
  return (
    <ButtonGroup>
      <Button variant="secondary">Button 1</Button>
      <ButtonGroupSeparator />
      <Button variant="secondary">Button 2</Button>
    </ButtonGroup>
  )
}

Split

Create a split button group by adding two buttons separated by a ButtonGroupSeparator.

import { ChevronDownIcon, SendIcon } from "lucide-react"
 
import { Button } from "@/components/ui/button"
import {
  ButtonGroup,
  ButtonGroupSeparator,
} from "@/components/ui/button-group"
 
export function ButtonGroupSplitExample() {
  return (
    <ButtonGroup>
      <Button variant="outline">
        <SendIcon data-icon="inline-start" />
        Send
      </Button>
      <ButtonGroupSeparator />
      <Button variant="outline" size="icon" aria-label="More options">
        <ChevronDownIcon />
      </Button>
    </ButtonGroup>
  )
}

Input

Wrap an Input component with buttons.

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
import { Input } from "@/components/ui/input"
 
export function ButtonGroupInputExample() {
  return (
    <ButtonGroup>
      <Input placeholder="Search components" className="w-56" />
      <Button variant="outline">Search</Button>
    </ButtonGroup>
  )
}

Input Group

Wrap an InputGroup component to create complex input layouts.

import { SearchIcon } from "lucide-react"
 
import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
} from "@/components/ui/input-group"
 
export function ButtonGroupInputGroupExample() {
  return (
    <ButtonGroup>
      <InputGroup className="w-56">
        <InputGroupAddon align="inline-start">
          <SearchIcon />
        </InputGroupAddon>
        <InputGroupInput placeholder="Search components" />
      </InputGroup>
      <Button variant="outline">Search</Button>
    </ButtonGroup>
  )
}

Create a split button group with a DropdownMenu component.

import { ChevronDownIcon, SendIcon } from "lucide-react"
 
import { Button } from "@/components/ui/button"
import {
  ButtonGroup,
  ButtonGroupSeparator,
} from "@/components/ui/button-group"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
 
export function ButtonGroupDropdownExample() {
  return (
    <ButtonGroup>
      <Button variant="outline">
        <SendIcon data-icon="inline-start" />
        Send
      </Button>
      <ButtonGroupSeparator />
      <DropdownMenu>
        <DropdownMenuTrigger
          render={
            <Button variant="outline" size="icon" aria-label="More options">
              <ChevronDownIcon />
            </Button>
          }
        />
        <DropdownMenuContent align="end">
          <DropdownMenuItem>Send now</DropdownMenuItem>
          <DropdownMenuItem>Schedule send</DropdownMenuItem>
          <DropdownMenuItem>Save as draft</DropdownMenuItem>
        </DropdownMenuContent>
      </DropdownMenu>
    </ButtonGroup>
  )
}

Select

Pair with a Select component.

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select"
 
export function ButtonGroupSelectExample() {
  return (
    <ButtonGroup>
      <Select defaultValue="next">
        <SelectTrigger className="w-36">
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          <SelectItem value="next">Next.js</SelectItem>
          <SelectItem value="svelte">SvelteKit</SelectItem>
          <SelectItem value="nuxt">Nuxt.js</SelectItem>
        </SelectContent>
      </Select>
      <Button variant="outline">Deploy</Button>
    </ButtonGroup>
  )
}

Use with a Popover component.

import { SettingsIcon } from "lucide-react"
 
import { Button } from "@/components/ui/button"
import {
  ButtonGroup,
  ButtonGroupSeparator,
} from "@/components/ui/button-group"
import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@/components/ui/popover"
 
export function ButtonGroupPopoverExample() {
  return (
    <ButtonGroup>
      <Button variant="outline">Save</Button>
      <ButtonGroupSeparator />
      <Popover>
        <PopoverTrigger
          render={
            <Button variant="outline" size="icon" aria-label="More settings">
              <SettingsIcon />
            </Button>
          }
        />
        <PopoverContent align="end" className="w-64">
          <p className="text-sm font-medium">Save options</p>
          <p className="mt-1.5 text-sm leading-relaxed text-muted-foreground">
            Choose whether to save a draft or publish immediately.
          </p>
        </PopoverContent>
      </Popover>
    </ButtonGroup>
  )
}

RTL

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
 
export function ButtonGroupRtlExample() {
  return (
    <ButtonGroup>
      <Button variant="outline">دکمه ۱</Button>
      <Button variant="outline">دکمه ۲</Button>
    </ButtonGroup>
  )
}

API Reference

ButtonGroup

Prop	Type	Default	Description
orientation	"horizontal" \| "vertical"	"horizontal"	The layout flow direction of the button group.

ButtonGroupSeparator

Prop	Type	Default	Description
orientation	"horizontal" \| "vertical"	"vertical"	The orientation of the separator.

ButtonGroupText

Prop	Type	Default	Description
asChild	boolean	false	Renders the passed child element instead of a plain div, merging in the text styles.

Edit this page on GitHub

PreviousButton NextCard