Question 1

What is a shadcn button group?

Accepted Answer

A shadcn button group is a row of related buttons rendered as a single connected unit — segmented controls, action toolbars, split buttons (primary action + dropdown), pagination clusters, view-mode togglers. The corners are joined so the group reads as one cohesive control rather than scattered buttons. It's built on the shadcn/ui ButtonGroup primitive (handles connected borders, divider lines, focus management) and styled with Tailwind CSS. Each example in this gallery is a single self-contained TSX file — copy, paste, and ship.

Question 2

Are these button group examples free?

Accepted Answer

Yes. Every button group example on shadcn.io is free to copy and use in personal or commercial projects. There's no gated source, no attribution requirement, and no runtime dependency on shadcn.io. Browse any example, view the code, run the installer, and move on.

Question 3

How is this different from just placing buttons next to each other?

Accepted Answer

Three things. (1) Visual cohesion — adjacent borders are merged so the group reads as one element, with internal dividers instead of doubled borders. (2) Corner radius — only the first/last children get rounded corners; inner buttons are square so they butt up cleanly. (3) Consistent sizing — passing `size="sm"` to the group cascades down to every Button child without you setting it on each one. Save 30 lines of repetitive className per group.

Question 4

When should I use a button group versus a Toggle Group or a Tabs?

Accepted Answer

ButtonGroup for actions that DO something (split buttons, toolbars, pagination — "Run", "Stop", "Step"). ToggleGroup for selection — single or multi-select state that persists between interactions (text-alignment selector, formatting bar). Tabs for switching CONTENT (panes, views) where only one is visible at a time. Pick by intent: action, selection, or view switch.

Question 5

Should I use a horizontal or vertical button group?

Accepted Answer

Horizontal is the default and works for most use cases — split buttons, view-mode pickers, action toolbars. Vertical works for sidebar navigation strips, mobile menus, or when horizontal space is constrained. Both share the same connected-corner styling; the orientation just changes which corners get rounded. Avoid switching orientation between breakpoints — users adapt to one or the other.

Question 6

How do I build a split button (primary action + dropdown)?

Accepted Answer

Use the actions variant. Wrap a primary Button and a DropdownMenuTrigger Button inside a ButtonGroup. The trigger button is usually icon-only (`size="icon"`) with a ChevronDown. The dropdown menu offers secondary actions related to the primary one ("Save" + dropdown for "Save as…", "Save and continue", "Discard"). Keep the primary action visually dominant — the dropdown is the secondary affordance.

Question 7

How do I add a Badge or count indicator inside a button group?

Accepted Answer

See the badges variant. Render a small Badge inside the Button as the last child, with `gap-1.5` between the label and badge. Common in pagination groups ("Inbox 23"), filter groups ("Active 5"), or step trackers. Keep the badge size proportional to the button — Badge inside a sm button should be `text-[10px]`, inside default Button `text-xs`. Avoid badges on every button; reserve them for buttons with quantitative state.

Question 8

How do I show which button in the group is currently active?

Accepted Answer

Drive the active state with a local state value, then pass `variant="default"` (solid) to the active button and `variant="ghost"` or `"outline"` to the inactive ones. For a single-select group (segmented control), use `<ToggleGroup type="single">` instead — it manages the active state for you and emits `aria-pressed` / `aria-current` automatically. ButtonGroup itself doesn't manage state; it's purely visual.

Question 9

How do I install a button group example?

Accepted Answer

Run the `npx shadcn@latest add` command shown under the Installation heading on any example's detail page. The shadcn CLI copies the example's TSX source into your project at `components/examples/button-group/…`, plus the shadcn/ui ButtonGroup primitive (and Button) if you don't already have it. Customize labels, icons, and click handlers in place.

Question 10

How do I make a button group responsive — collapse on mobile?

Accepted Answer

Two patterns. (1) Hide individual buttons at narrow widths via `hidden md:inline-flex` on each Button — the group naturally tightens. (2) Replace the entire group with a DropdownMenu on mobile: render `…` and `…` side by side, picking one per breakpoint. Pattern (2) is better for groups with many buttons (5+); pattern (1) is fine for 3–4.

Question 11

Can I mix button variants within a single group?

Accepted Answer

Yes — see the patterns variant. A common pattern is a destructive button + secondary buttons + ghost buttons in the same group (e.g. "Delete" + "Cancel" + "More options ▾"). Keep the destructive button visually distinct (red) and place it at the far edge so users have to look at it to click it. Don't mix more than two variants in a single group; three or more makes the visual hierarchy unclear.

Question 12

How do I keep button group sizing consistent?

Accepted Answer

Set the size prop on the ButtonGroup (`size="sm"` / `"default"` / `"lg"`) instead of on each child Button — the size cascades down via context. For groups with mixed labels and icons, give every button the same min-width (`min-w-[80px]`) so the group reads as a tidy strip rather than a ragged edge. Tabular numbers (`tabular-nums`) for any numeric labels prevents column-shift on count updates.

Question 13

Which libraries do button group examples depend on?

Accepted Answer

shadcn/ui ButtonGroup and Button (the styled wrappers generated into your project by the CLI), Tailwind CSS (styling), class-variance-authority (the variant API), Radix UI Slot (powers asChild composition), and Lucide React (icons). Patterns with dropdowns add DropdownMenu — also a single shadcn primitive away. TypeScript is assumed. React 19 is the baseline.

Question 14

Are button group examples accessible for keyboard and screen reader users?

Accepted Answer

Yes. ButtonGroup renders as a `role="group"` element with an optional `aria-label`, so screen readers announce the group's purpose. Each child Button is a real `<button>` and keyboard-focusable in DOM order. For toggle-style groups (segmented controls), use `aria-pressed="true"` on the active button. For navigation-style groups, `aria-current="page"` is more appropriate than `aria-pressed`.

Question 15

Can I use these button group examples with React Server Components?

Accepted Answer

Yes — the ButtonGroup primitive is pure render with no client state. Buttons inside that have onClick handlers need a client boundary, but the wrapper itself renders cleanly on the server. Pattern: keep the ButtonGroup in a Server Component, and lift only the active-state and onClick logic into a child client component if needed.

Question 16

Do these examples work with Tailwind CSS v3 and v4?

Accepted Answer

Both. shadcn.io is authored on Tailwind v4, so the examples use the v4 class names and design tokens. If you're on Tailwind v3, the classes still apply — Tailwind v4 introduced opt-in features but kept the utility naming compatible. The connected-border styling uses standard rounded-l-* / rounded-r-* utilities that exist identically across versions.

React Button Group Examples for shadcn/ui

Browse every button group example

Frequently Asked Questions