snapshot of https://github.com/shadcn-ui/ui.git (main, 2026-09-15; blobs > 131072B omitted)
This commit is contained in:
upstream-mirror
243
apps/v4/content/docs/components/radix/button-group.mdx
Normal file
243
apps/v4/content/docs/components/radix/button-group.mdx
Normal file
@@ -0,0 +1,243 @@
|
||||
---
|
||||
title: Button Group
|
||||
description: A container that groups related buttons together with consistent styling.
|
||||
base: radix
|
||||
component: true
|
||||
---
|
||||
|
||||
<ComponentPreview styleName="radix-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 radix-ui
|
||||
```
|
||||
|
||||
<Step>Copy and paste the following code into your project.</Step>
|
||||
|
||||
<ComponentSource
|
||||
name="button-group"
|
||||
title="components/ui/button-group.tsx"
|
||||
styleName="radix-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="radix-nova" name="button-group-orientation" />
|
||||
|
||||
## Size
|
||||
|
||||
Control the size of buttons using the `size` prop on individual buttons.
|
||||
|
||||
<ComponentPreview styleName="radix-nova" name="button-group-size" />
|
||||
|
||||
## Nested
|
||||
|
||||
Nest `<ButtonGroup>` components to create button groups with spacing.
|
||||
|
||||
<ComponentPreview styleName="radix-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="radix-nova" name="button-group-separator" />
|
||||
|
||||
## Split
|
||||
|
||||
Create a split button group by adding two buttons separated by a `ButtonGroupSeparator`.
|
||||
|
||||
<ComponentPreview styleName="radix-nova" name="button-group-split" />
|
||||
|
||||
## Input
|
||||
|
||||
Wrap an `Input` component with buttons.
|
||||
|
||||
<ComponentPreview styleName="radix-nova" name="button-group-input" />
|
||||
|
||||
## Input Group
|
||||
|
||||
Wrap an `InputGroup` component to create complex input layouts.
|
||||
|
||||
<ComponentPreview styleName="radix-nova" name="button-group-input-group" />
|
||||
|
||||
## Dropdown Menu
|
||||
|
||||
Create a split button group with a `DropdownMenu` component.
|
||||
|
||||
<ComponentPreview styleName="radix-nova" name="button-group-dropdown" />
|
||||
|
||||
## Select
|
||||
|
||||
Pair with a `Select` component.
|
||||
|
||||
<ComponentPreview styleName="radix-nova" name="button-group-select" />
|
||||
|
||||
## Popover
|
||||
|
||||
Use with a `Popover` component.
|
||||
|
||||
<ComponentPreview styleName="radix-nova" name="button-group-popover" />
|
||||
|
||||
## RTL
|
||||
|
||||
To enable RTL support in shadcn/ui, see the [RTL configuration guide](/docs/rtl).
|
||||
|
||||
<ComponentPreview
|
||||
styleName="radix-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 |
|
||||
| --------- | --------- | ------- |
|
||||
| `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>
|
||||
)
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user