248 lines
5.4 KiB
Plaintext
248 lines
5.4 KiB
Plaintext
---
|
|
title: Button Group
|
|
description: A container that groups related buttons together with consistent styling.
|
|
base: aria
|
|
component: true
|
|
---
|
|
|
|
<ComponentPreview styleName="aria-nova" name="button-group-demo" />
|
|
|
|
## Installation
|
|
|
|
<CodeTabs>
|
|
|
|
<TabsList>
|
|
<TabsTrigger value="cli">Command</TabsTrigger>
|
|
<TabsTrigger value="manual">Manual</TabsTrigger>
|
|
</TabsList>
|
|
<TabsContent value="cli">
|
|
|
|
```bash
|
|
npx shadcn@latest add button-group
|
|
```
|
|
|
|
</TabsContent>
|
|
|
|
<TabsContent value="manual">
|
|
|
|
<Steps className="mb-0 pt-2">
|
|
|
|
<Step>Install the following dependencies:</Step>
|
|
|
|
```bash
|
|
npm install react-aria-components
|
|
```
|
|
|
|
<Step>Copy and paste the following code into your project.</Step>
|
|
|
|
<ComponentSource
|
|
name="button-group"
|
|
title="components/ui/button-group.tsx"
|
|
styleName="aria-nova"
|
|
/>
|
|
|
|
<Step>Update the import paths to match your project setup.</Step>
|
|
|
|
</Steps>
|
|
|
|
</TabsContent>
|
|
|
|
</CodeTabs>
|
|
|
|
## 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 <Kbd>Tab</Kbd> 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.
|
|
|
|
<ComponentPreview styleName="aria-nova" name="button-group-orientation" />
|
|
|
|
## Size
|
|
|
|
Control the size of buttons using the `size` prop on individual buttons.
|
|
|
|
<ComponentPreview styleName="aria-nova" name="button-group-size" />
|
|
|
|
## Nested
|
|
|
|
Nest `<ButtonGroup>` components to create button groups with spacing.
|
|
|
|
<ComponentPreview styleName="aria-nova" name="button-group-nested" />
|
|
|
|
## 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.
|
|
|
|
<ComponentPreview styleName="aria-nova" name="button-group-separator" />
|
|
|
|
## Split
|
|
|
|
Create a split button group by adding two buttons separated by a `ButtonGroupSeparator`.
|
|
|
|
<ComponentPreview styleName="aria-nova" name="button-group-split" />
|
|
|
|
## Input
|
|
|
|
Wrap an `Input` component with buttons.
|
|
|
|
<ComponentPreview styleName="aria-nova" name="button-group-input" />
|
|
|
|
## Input Group
|
|
|
|
Wrap an `InputGroup` component to create complex input layouts.
|
|
|
|
<ComponentPreview styleName="aria-nova" name="button-group-input-group" />
|
|
|
|
## Dropdown Menu
|
|
|
|
Create a split button group with a `DropdownMenu` component.
|
|
|
|
<ComponentPreview styleName="aria-nova" name="button-group-dropdown" />
|
|
|
|
## Select
|
|
|
|
Pair with a `Select` component.
|
|
|
|
<ComponentPreview styleName="aria-nova" name="button-group-select" />
|
|
|
|
## Popover
|
|
|
|
Use with a `Popover` component.
|
|
|
|
<ComponentPreview styleName="aria-nova" name="button-group-popover" />
|
|
|
|
## RTL
|
|
|
|
To enable RTL support in shadcn/ui, see the [RTL configuration guide](/docs/rtl).
|
|
|
|
<ComponentPreview
|
|
styleName="aria-nova"
|
|
name="button-group-rtl"
|
|
direction="rtl"
|
|
/>
|
|
|
|
## 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 |
|
|
| -------- | --------- | ------- |
|
|
| `render` | `boolean` | `false` |
|
|
|
|
```tsx
|
|
<ButtonGroup>
|
|
<ButtonGroupText>Text</ButtonGroupText>
|
|
<Button>Button</Button>
|
|
</ButtonGroup>
|
|
```
|
|
|
|
Use the `render` 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
|
|
render={(props) => (
|
|
<Label {...props} htmlFor="name">
|
|
Text
|
|
</Label>
|
|
)}
|
|
/>
|
|
<Input placeholder="Type something here..." id="name" />
|
|
</ButtonGroup>
|
|
)
|
|
}
|
|
```
|