Button Group

A row of related actions on one shared surface

Composablebuilt onButton

A button group puts related actions on one surface, like a file's share, duplicate, and archive, or an editor's undo and redo. A highlight glides between the buttons as you hover or tab along the row.

When one button stays selected, use ToggleGroup. When the row needs arrow-key navigation, use Toolbar.

Preview

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

Installation

npxnpx shadcn@latest add @cubby-ui/button-group

Usage


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


<ButtonGroup>
  <ButtonGroupSeparator />
</ButtonGroup>

Composition

ButtonGroup
├── Button
├── ButtonGroupSeparator
└── ButtonGroupText

Leave variant unset on the buttons inside; they take the group's style.

A shell never gets narrower than its buttons. If it may not fit on small screens, put it in a container that scrolls sideways, such as a ScrollArea with nativeScroll. To let a field shrink instead, pass className="min-w-0" to the group.

Examples

Variants

Use variant to pick the shell the buttons sit on.

Variant	Description
`outline`	The default. An outline Button's fill and border.
`soft`	A secondary Button's fill, for editor chrome.
`elevated`	A raised surface, for toolbars that float.
`solid`	The neutral fill, for a primary action and options.
`attached`	No shell; joins buttons to fields. See Attached.

Separator

Use ButtonGroupSeparator to split actions into clusters; it hides beside the highlight.

Emphasis

Give one button a variant to mark the main action; it keeps its own fill.

import { Button } from "@/components/ui/cubby-ui/button";
import { ButtonGroup } from "@/components/ui/cubby-ui/button-group/button-group";
 
import { HugeiconsIcon } from "@hugeicons/react";
import {
  Archive02Icon,

Pill

Set [--radius:9999px] on the group for a pill; the buttons' corners follow.


<ButtonGroup className="[--radius:9999px]">…</ButtonGroup>

With Text

Use ButtonGroupText for a read-only label between buttons, like a selection count. For a value people type or step, use NumberField.

3 selected

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

With Fields

Put an Input or Select in a shell and it drops its border to sit in the row like a button.

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

Pair an action with a menu of related ones; the trigger keeps the highlight while the menu is open.

Orientation

Set orientation="vertical" to stack the buttons; separators turn to match.

Size

Use size to match the group's height to a Button of the same size. Icon-only buttons still need an icon size to stay square.

import { Button } from "@/components/ui/cubby-ui/button";
import { ButtonGroup } from "@/components/ui/cubby-ui/button-group/button-group";
 
import { HugeiconsIcon } from "@hugeicons/react";
import {
  TextBoldIcon,

Nested

Nest groups to lay out several shells; inner groups inherit the outer variant and size.

import { Button } from "@/components/ui/cubby-ui/button";
import { ButtonGroup } from "@/components/ui/cubby-ui/button-group/button-group";
 
import { HugeiconsIcon } from "@hugeicons/react";
import { ChevronLeftIcon, ChevronRightIcon } from "@hugeicons/core-free-icons";

Attached

Use variant="attached" to join buttons, inputs, and selects into one control, with their own borders and variants.

import { Button } from "@/components/ui/cubby-ui/button";
import { ButtonGroup } from "@/components/ui/cubby-ui/button-group/button-group";
 
export default function ButtonGroupAttached() {
  return (
    <ButtonGroup variant="attached" aria-label="Date range">

import { Button } from "@/components/ui/cubby-ui/button";
import { ButtonGroup } from "@/components/ui/cubby-ui/button-group/button-group";
import { Input } from "@/components/ui/cubby-ui/input";
 
import { HugeiconsIcon } from "@hugeicons/react";
import { Search01Icon } from "@hugeicons/core-free-icons";

import { Button } from "@/components/ui/cubby-ui/button";
import { ButtonGroup } from "@/components/ui/cubby-ui/button-group/button-group";
import { Input } from "@/components/ui/cubby-ui/input";
import {
  Select,
  SelectContent,

import { Button } from "@/components/ui/cubby-ui/button";
import { ButtonGroup } from "@/components/ui/cubby-ui/button-group/button-group";
import { Input } from "@/components/ui/cubby-ui/input";
import { Label } from "@/components/ui/cubby-ui/label";
import {
  Popover,

"use client";
 
import * as React from "react";
 
import { Button } from "@/components/ui/cubby-ui/button";
import { ButtonGroup } from "@/components/ui/cubby-ui/button-group/button-group";

Accessibility

Labels

The group renders role="group". Give it an aria-label that names the set ("File actions"), and give every icon-only button its own.

Keyboard

Tab moves through the buttons one at a time. For arrow-key navigation along a long row, use Toolbar.

Highlight

The highlight follows the pointer and keyboard focus and skips disabled buttons. Focus also draws a ring, so the highlight is never the only cue. With reduced motion, it jumps instead of sliding. Browsers without CSS anchor positioning show a hover color on each button instead.

Before	Now
Installed as `cubby-ui/button-group.tsx`	Installs into a `cubby-ui/button-group/` folder with `button-group.css`. Import from `@/components/ui/cubby-ui/button-group/button-group` and delete the old file.
Children fused into one bordered control	The default is `outline`, a shell. Pass `variant="attached"` for the old look.
`ButtonGroupSeparator` defaulted to vertical	It turns perpendicular to the group, so vertical groups need no `orientation`.
Buttons in a group set `variant="outline"`	Leave `variant` unset in a shell. A set variant marks the button as the main action.