Component

Button Group

A set of related buttons joined into a single connected control. Ideal for toggleable or segmented options.

Installation

Install from the live registry into any shadcn-initialized app (another project). Prefer installing ag-globals first so AG tokens and fonts are present.

npx shadcn@latest add https://design.ag.org/r/button-group

Usage

Use button groups for tightly related actions or view-switching (e.g. List / Grid). Avoid grouping more than 5 buttons.

Composition

Button

Playground

Preview

Configure

Variant

Code

"use client"

import { useState } from "react"
import { ButtonGroup, ButtonGroupItem } from "@/components/ui/button-group"

export function ViewSwitcher() {
  const [active, setActive] = useState(0)

  return (
    <ButtonGroup variant="outline">
      <ButtonGroupItem variant="outline" active={active === 0} onClick={() => setActive(0)}>Day</ButtonGroupItem>
      <ButtonGroupItem variant="outline" active={active === 1} onClick={() => setActive(1)}>Week</ButtonGroupItem>
      <ButtonGroupItem variant="outline" active={active === 2} onClick={() => setActive(2)}>Month</ButtonGroupItem>
    </ButtonGroup>
  )
}

Variants & States

Supported variants, sizes, and interaction states for this component.

Variants

Outline
Secondary

States

Inactive item
Active item

Do

Use for 2–5 closely related options
Visually distinguish the active/selected button
Keep button labels short, 1–2 words each

Don't

Don't use more than 5 buttons in a group, use a Select instead
Don't mix icon-only and label buttons in the same group