# ButtonGroup

- Page: https://jiguang132.com/resources/astryx/docs/button-group
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

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

```bash
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](/resources/astryx/docs/getting-started).

## 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

```json
{
  "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.

| Prop | Type | Default | Description |
|---|---|---|---|
| children * | ReactNode |  | Button or IconButton children. |
| label * | string |  | Accessible label for the group (aria-label). |
| orientation | 'horizontal' \| 'vertical' | 'horizontal' | Layout direction of the button group. |
| size | 'sm' \| 'md' \| 'lg' | 'md' | Default size for buttons in the group. Individual buttons can override. |
| isDisabled | boolean | false | Whether all buttons in the group are disabled. |
| elevation | 'none' \| 'low' \| 'med' \| 'high' | 'none' | Resting shadow depth for the whole group. The connected buttons share one surface, so the shadow lifts them as a unit. Use for a group that floats above content. |
| ref | React.Ref<HTMLDivElement> |  | Ref forwarded to the root element. |
| xstyle | StyleXStyles |  | StyleX styles for layout customization. Must be a stylex.create() value. |
| data-testid | string |  | Test selector for automated testing frameworks. |

### 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:

```bash
npm install @heroicons/react@2.2.0
```

---

Index of all JGuang resources: https://jiguang132.com/llms.txt