ButtonGroup

ButtonGroup joins related actions into a single connected control. Use it when multiple buttons represent related choices or operations that belong together visually, like copy/cut/paste, or undo/redo.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

Button Group

ButtonGroup joins related actions into a single connected control. Use it when multiple buttons represent related choices or operations that belong together visually, like copy/cut/paste, or undo/redo.

Usage guidance

• Group buttons that perform related actions on the same object, like copy, cut, paste on selected text.
• Use the same variant for all buttons in a group so they look like a single connected unit.
• Keep groups small (2–4 buttons). For more actions, use a Toolbar or DropdownMenu instead.
• Avoid: Don't mix wildly different actions. A Save button next to a Delete button in the same group is confusing.
• Avoid: Don't use ButtonGroup for navigation. Use SegmentedControl or TabList for switching between views.
• Avoid: Don't nest ButtonGroups. If you need multiple groups, place them side by side with a gap.
• Name the group for what its buttons act on. The label is the group's accessible name and a screen reader reads it before each member.
• Keep the group a single Tab stop. Arrow keys move between members along the orientation, Home/End jump to the ends, and disabled members are skipped. This is the WAI-ARIA APG roving tabindex technique: https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex
• Avoid: Don't disable the group to show that an action is in flight. A disabled member drops focus, so a keyboard user loses their place; leave the group enabled and show progress on the button that started the work.

Theming API

{
  "targets": [
    {
      "className": "astryx-button-group",
      "visualProps": [
        "size",
        "orientation",
        "elevation"
      ]
    }
  ]
}

Button Group

Groups multiple buttons together with connected styling: shared borders, proper border-radius handling (only on outer edges), and horizontal or vertical orientation.

Accessibility

• Text label: Text in each button must have at least 4.5:1 contrast with its background in every state. For Hover and Pointer down, measure the final background after the overlay is applied. — 4.5:1
• Essential icon or spinner arc: An icon used instead of text must have at least 3:1 contrast with the button background. The moving spinner arc must also meet 3:1. An icon beside a visible label does not need its own check. — 3:1
• Visible control boundary: Some groups need a divider or edge to show each button. That divider or edge must have at least 3:1 contrast. — 3:1 if needed
• Keyboard focus indicator: The focus outline must have at least 3:1 contrast with the area around it. — 3:1
• Disabled appearance: Disabled controls do not need to meet these contrast ratios. — Not required

Anatomy

• Button: One or more Button or IconButton children that form the connected group.
• Divider: A thin border between buttons, rendered automatically by the group.

Examples

• Button Group:
• ButtonGroup — Basic: Three related actions joined into a single connected control. Provide a group label for accessibility and keep all buttons the same variant so they read as one unit.
• ButtonGroup — Floating: A grouped action bar raised with elevation="med". The connected buttons share one surface, so the shadow lifts them as a unit.

Complete example dependencies

Some examples import optional icons. The per-example install command in the examples list identifies exactly what that example needs. For all examples on this page:

npm install @heroicons/react@2.2.0