# Button Group · JGuang UI

> A container that groups related buttons together with consistent styling.

- Page: https://jiguang132.com/systems/jguang-ui/docs/components/base/button-group
- Based on: shadcn/ui documentation (MIT) @ bc0705384b51252af26dcc65425b216bf5eb063c

> Example `button-group-demo`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/button-group


## Installation


  

**Command**


  

**Manual**


```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```


### Install the following dependencies:


```bash
npm install @base-ui/react
```


### Copy and paste the following code into your project.


[View complete source: components/ui/button-group.tsx](/r/jguang-ui/base/button-group.json)


### Update the import paths to match your project setup.


## Usage

```tsx
import {
  ButtonGroup,
  ButtonGroupSeparator,
  ButtonGroupText,
} from "@/components/ui/button-group"
```

```tsx
<ButtonGroup>
  <Button>Button 1</Button>
  <Button>Button 2</Button>
</ButtonGroup>
```

## Composition

Use the following composition to build a `ButtonGroup`:

```text
ButtonGroup
├── Button or Input
├── ButtonGroupSeparator
└── ButtonGroupText
```

## Accessibility

- The `ButtonGroup` component has the `role` attribute set to `group`.
- Use 
Tab
 to navigate between the buttons in the group.
- Use `aria-label` or `aria-labelledby` to label the button group.

```tsx showLineNumbers
<ButtonGroup aria-label="Button group">
  <Button>Button 1</Button>
  <Button>Button 2</Button>
</ButtonGroup>
```

## ButtonGroup vs ToggleGroup

- Use the `ButtonGroup` component when you want to group buttons that perform an action.
- Use the `ToggleGroup` component when you want to group buttons that toggle a state.

## Orientation

Set the `orientation` prop to change the button group layout.


> Example `button-group-orientation`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/button-group


## Size

Control the size of buttons using the `size` prop on individual buttons.


> Example `button-group-size`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/button-group


## Nested

Nest `<ButtonGroup>` components to create button groups with spacing.


> Example `button-group-nested`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/button-group


## Separator

The `ButtonGroupSeparator` component visually divides buttons within a group.

Buttons with variant `outline` do not need a separator since they have a border. For other variants, a separator is recommended to improve the visual hierarchy.


> Example `button-group-separator`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/button-group


## Split

Create a split button group by adding two buttons separated by a `ButtonGroupSeparator`.


> Example `button-group-split`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/button-group


## Input

Wrap an `Input` component with buttons.


> Example `button-group-input`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/button-group


## Input Group

Wrap an `InputGroup` component to create complex input layouts.


> Example `button-group-input-group`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/button-group


## Dropdown Menu

Create a split button group with a `DropdownMenu` component.


> Example `button-group-dropdown`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/button-group


## Select

Pair with a `Select` component.


> Example `button-group-select`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/button-group


## Popover

Use with a `Popover` component.


> Example `button-group-popover`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/button-group


## RTL

To enable RTL support in JGuang UI, see the [RTL configuration guide](/systems/jguang-ui/docs/rtl).


> Example `button-group-rtl`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/button-group


## API Reference

### ButtonGroup

The `ButtonGroup` component is a container that groups related buttons together with consistent styling.

| Prop          | Type                         | Default        |
| ------------- | ---------------------------- | -------------- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |

```tsx
<ButtonGroup>
  <Button>Button 1</Button>
  <Button>Button 2</Button>
</ButtonGroup>
```

Nest multiple button groups to create complex layouts with spacing. See the [nested](#nested) example for more details.

```tsx
<ButtonGroup>
  <ButtonGroup />
  <ButtonGroup />
</ButtonGroup>
```

### ButtonGroupSeparator

The `ButtonGroupSeparator` component visually divides buttons within a group.

| Prop          | Type                         | Default      |
| ------------- | ---------------------------- | ------------ |
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` |

```tsx
<ButtonGroup>
  <Button>Button 1</Button>
  <ButtonGroupSeparator />
  <Button>Button 2</Button>
</ButtonGroup>
```

### ButtonGroupText

Use this component to display text within a button group.

| Prop      | Type      | Default |
| --------- | --------- | ------- |
| `asChild` | `boolean` | `false` |

```tsx
<ButtonGroup>
  <ButtonGroupText>Text</ButtonGroupText>
  <Button>Button</Button>
</ButtonGroup>
```

Use the `asChild` prop to render a custom component as the text, for example a label.

```tsx showLineNumbers
import { ButtonGroupText } from "@/components/ui/button-group"
import { Label } from "@/components/ui/label"

export function ButtonGroupTextDemo() {
  return (
    <ButtonGroup>
      <ButtonGroupText asChild>
        <Label htmlFor="name">Text</Label>
      </ButtonGroupText>
      <Input placeholder="Type something here..." id="name" />
    </ButtonGroup>
  )
}
```

---

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