Inputs/Button Group

Button Group

Groups multiple buttons together with consistent styling.

Themed

When to Use

Use the ButtonGroup when you need to:

  • Group related action buttons together (e.g., Archive, Report, Delete)
  • Create split buttons with a main action and secondary options
  • Combine inputs with action buttons (e.g., search bars, URL inputs)
  • Display mutually exclusive actions that belong together visually
  • Build toolbar-style button arrangements with consistent spacing

When Not to Use

  • For toggle states (Bold, Italic, Underline) — use ToggleGroup instead
  • For navigation between views — use Tabs instead
  • For single actions that don't need grouping — use Button alone
  • For pagination controls — use Pagination instead

Default

A comprehensive example showing nested button groups with dropdown menus.

Basic Usage

With Separator

With Text Label

Quantity

Nested Groups (with spacing)

Split Button with Dropdown

With Input

Vertical Orientation

Orientation

Set the orientation prop to change the button group layout between horizontal and vertical.

Horizontal
Vertical

Size

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

Small
Default
Large

Nested

Nest ButtonGroup components to create button groups with spacing between them.

Separator

Use ButtonGroupSeparator to visually divide buttons within a group.

Buttons with variant outline do not need a separator since they have a border. For other variants, a separator improves visual hierarchy.

Split

Create a split button by combining a main action button with an icon button.

Input

Wrap an Input component with buttons to create search bars or combined input layouts.

Dropdown Menu

Create a split button group with a DropdownMenu for additional actions.

Select

Pair with a Select component for currency selectors or other combined inputs.

Popover

Use with a Popover component for expanded functionality.

Text

Use ButtonGroupText to display labels within a button group.

Quantity
Volume

Accessibility

Best practices for accessible button groups.

Use aria-label to provide accessible names for button groups. Use Tab to navigate between buttons.

ButtonGroup vs ToggleGroup

  • ButtonGroup: Use when you want to group buttons that perform an action (e.g., Archive, Report, Delete).
  • ToggleGroup: Use when you want to group buttons that toggle a state (e.g., Bold, Italic, Underline formatting).

UX & Design Guidelines

Visual Hierarchy

Place the primary action first in the group. Use variant="default" for the main action and variant="outline" for secondary actions. Split buttons should have the main action on the left with the dropdown trigger on the right.

Spacing & Layout

ButtonGroup automatically removes spacing between buttons and adjusts border-radius. Use nested ButtonGroups with gap-2 for visual separation between related but distinct groups. Vertical orientation works best for toolbars in sidebars or narrow containers.

Responsive Behavior

On mobile viewports (320px+), consider switching from horizontal to vertical orientation for better touch targets. Use size="sm" buttons on mobile only if space is constrained, as larger targets improve accessibility.

Color & Contrast

All button variants within groups meet WCAG 2.1 AA contrast requirements. Use semantic colors for actions: variant="destructive" for delete/remove actions. Design tokens ensure consistent theming across light and dark modes.

Grouping Principles

Limit groups to 5-7 buttons maximum for cognitive load. Group by function (e.g., clipboard actions together, navigation together). Use separators sparingly to indicate major functional divisions.

Accessibility

Keyboard Navigation

  • Tab — Move focus to the next button in the group
  • Shift + Tab — Move focus to the previous button
  • Enter or Space — Activate the focused button
  • Escape — Close any open dropdown or popover

Screen Reader Support

  • ButtonGroup renders with role="group" to announce related buttons
  • Use aria-label on the group to describe its purpose
  • Icon-only buttons must have aria-label describing the action
  • Disabled buttons are properly announced with their state

Focus Management

Each button maintains visible focus indicators with focus-visible:ring-2. The z-index is automatically elevated on focused buttons to ensure the ring is fully visible even in tightly packed groups. Focus order follows DOM order (left-to-right for horizontal, top-to-bottom for vertical).

ARIA Attributes

Touch Targets

Minimum touch target size is 44x44 pixels per WCAG 2.1 Level AAA. Default and larger button sizes meet this requirement. For size="sm", consider adding padding or using larger sizes on touch devices.

Related Components

Button

The base button component used within ButtonGroup. Use alone for single actions.

ToggleGroup

For toggle states like Bold/Italic/Underline. Manages selected state automatically.

Dropdown Menu

Combine with ButtonGroup for split button patterns with expandable options.

Input

Pair with ButtonGroup for search bars and combined input+action layouts.

ButtonGroup

A container that groups related buttons together with consistent styling.

PropTypeDefaultDescription
orientation"horizontal" | "vertical""horizontal"The layout direction of the button group.
classNamestring—Additional CSS classes to apply to the button group.
aria-labelstring—Accessible label for the button group.

ButtonGroupSeparator

Visually divides buttons within a group.

PropTypeDefaultDescription
orientation"horizontal" | "vertical""vertical"The orientation of the separator line.

ButtonGroupText

Displays text or labels within a button group.

PropTypeDefaultDescription
asChildbooleanfalseWhen true, renders the child element as the text container (useful for Label components).