111k
新建

Button Group

PreviousNext

将相关按钮以一致样式组合在一起的容器。

Radix UIBase UI
"use client"

import * as React from "react"

安装

pnpm dlx shadcn@latest add button-group

用法

import {
  ButtonGroup,
  ButtonGroupSeparator,
  ButtonGroupText,
} from "@/components/ui/button-group"
<ButtonGroup>
  <Button>Button 1</Button>
  <Button>Button 2</Button>
</ButtonGroup>

可访问性

  • ButtonGroup 组件的 role 属性设置为 group。
  • 使用 Tab 在组内按钮之间导航。
  • 使用 aria-label 或 aria-labelledby 为按钮组命名。
<ButtonGroup aria-label="Button group">
  <Button>Button 1</Button>
  <Button>Button 2</Button>
</ButtonGroup>

ButtonGroup 与 ToggleGroup

  • 当你想分组执行操作的按钮时，使用 ButtonGroup 组件。
  • 当你想分组切换状态的按钮时，使用 ToggleGroup 组件。

示例

方向

使用 orientation 属性改变按钮组布局。

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
import { MinusIcon, PlusIcon } from "lucide-react"

尺寸

通过单个按钮上的 size 属性控制按钮尺寸。

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
import { PlusIcon } from "lucide-react"

嵌套

嵌套 <ButtonGroup> 组件可以创建带间距的按钮组。

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
import { Input } from "@/components/ui/input"

分隔符

ButtonGroupSeparator 组件会在组内视觉上分隔按钮。

outline 变体的按钮因为自带边框，所以不需要分隔符。其他变体建议使用分隔符，以增强视觉层级。

import { Button } from "@/components/ui/button"
import {
  ButtonGroup,

分裂按钮

通过在两个按钮之间加入 ButtonGroupSeparator 创建分裂按钮组。

import { Button } from "@/components/ui/button"
import {
  ButtonGroup,

输入框

用按钮包裹一个 Input 组件。

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
import { Input } from "@/components/ui/input"

输入组

包裹一个 InputGroup 组件，以创建复杂的输入布局。

"use client"

import * as React from "react"

下拉菜单

使用 DropdownMenu 组件创建一个分裂按钮组。

"use client"

import { Button } from "@/components/ui/button"

选择器

与 Select 组件搭配使用。

"use client"

import * as React from "react"

弹出层

与 Popover 组件一起使用。

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"

RTL

要在 shadcn/ui 中启用 RTL 支持，请参见 RTL 配置指南。

"use client"

import * as React from "react"

API 参考

ButtonGroup

ButtonGroup 组件是一个将相关按钮以一致样式组合在一起的容器。

PropTypeDefault
orientation"horizontal" | "vertical""horizontal"
<ButtonGroup>
  <Button>Button 1</Button>
  <Button>Button 2</Button>
</ButtonGroup>

嵌套多个按钮组可以创建带间距的复杂布局。更多细节请参见 嵌套 示例。

<ButtonGroup>
  <ButtonGroup />
  <ButtonGroup />
</ButtonGroup>

ButtonGroupSeparator

The ButtonGroupSeparator component visually divides buttons within a group.

PropTypeDefault
orientation"horizontal" | "vertical""vertical"
<ButtonGroup>
  <Button>Button 1</Button>
  <ButtonGroupSeparator />
  <Button>Button 2</Button>
</ButtonGroup>

ButtonGroupText

Use this component to display text within a button group.

PropTypeDefault
asChildbooleanfalse
<ButtonGroup>
  <ButtonGroupText>Text</ButtonGroupText>
  <Button>Button</Button>
</ButtonGroup>

使用 asChild 属性可以把自定义组件渲染为文本，例如标签。

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>
  )
}