# Button 按钮
**Category**: react
**URL**: https://www.heroui.com/cn/docs/react/components/button
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(buttons)/button.mdx
> 可点击的按钮组件，支持多种变体与状态。
***
## 引入
```tsx
import { Button } from '@heroui/react';
```
### 用法
```tsx
"use client";
import {Button} from "@heroui/react";
export function Basic() {
return ;
}
```
### 变体
```tsx
import {Button} from "@heroui/react";
export function Variants() {
return (
);
}
```
### 带图标
```tsx
import {Envelope, Globe, Plus, TrashBin} from "@gravity-ui/icons";
import {Button} from "@heroui/react";
export function WithIcons() {
return (
);
}
```
### 仅图标
```tsx
import {Ellipsis, Gear, TrashBin} from "@gravity-ui/icons";
import {Button} from "@heroui/react";
export function IconOnly() {
return (
);
}
```
### 加载中
```tsx
"use client";
import {Button, Spinner} from "@heroui/react";
import React from "react";
export function Loading() {
return (
);
}
```
### 加载状态
```tsx
"use client";
import {Paperclip} from "@gravity-ui/icons";
import {Button, Spinner} from "@heroui/react";
import React, {useState} from "react";
export function LoadingState() {
const [isLoading, setLoading] = useState(false);
const handlePress = () => {
setLoading(true);
setTimeout(() => setLoading(false), 2000);
};
return (
);
}
```
### 尺寸
```tsx
import {Button} from "@heroui/react";
export function Sizes() {
return (
);
}
```
### 全宽
```tsx
import {Plus} from "@gravity-ui/icons";
import {Button} from "@heroui/react";
export function FullWidth() {
return (
);
}
```
### 禁用状态
```tsx
import {Button} from "@heroui/react";
export function Disabled() {
return (
);
}
```
### 社交按钮
```tsx
import {Button} from "@heroui/react";
import {Icon} from "@iconify/react";
export function Social() {
return (
);
}
```
### 自定义渲染函数
```tsx
"use client";
import {Button} from "@heroui/react";
export function CustomRenderFunction() {
return (
);
}
```
## Related Components
- **Popover**: Displays content in context with a trigger
- **Tooltip**: Contextual information on hover or focus
- **Form**: Form validation and submission handling
## 样式
### 传入 Tailwind CSS 类
```tsx
import { Button } from '@heroui/react';
function CustomButton() {
return (
);
}
```
### 自定义组件类
若要自定义 Button 组件类，可以使用 `@layer components` 指令。
[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。
```css
@layer components {
.button {
@apply bg-purple-500 text-white hover:bg-purple-600;
}
.button--icon-only {
@apply rounded-lg bg-blue-500;
}
}
```
HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。
### 添加自定义变体
你可以通过封装 HeroUI 组件并添加自定义变体来扩展其能力。
```tsx
import type {ButtonProps} from "@heroui/react";
import type {VariantProps} from "tailwind-variants";
import {Button, buttonVariants} from "@heroui/react";
import {tv} from "tailwind-variants";
const myButtonVariants = tv({
base: "text-md font-semibold shadow-md text-shadow-lg data-[pending=true]:opacity-40",
defaultVariants: {
radius: "full",
variant: "primary",
},
extend: buttonVariants,
variants: {
radius: {
full: "rounded-full",
lg: "rounded-lg",
md: "rounded-md",
sm: "rounded-sm",
},
size: {
lg: "h-12 px-8",
md: "h-11 px-6",
sm: "h-10 px-4",
xl: "h-13 px-10",
},
variant: {
primary: "text-white dark:bg-white/10 dark:text-white dark:hover:bg-white/15",
},
},
});
type MyButtonVariants = VariantProps;
export type MyButtonProps = Omit &
MyButtonVariants & {className?: string};
function CustomButton({className, radius, variant, ...props}: MyButtonProps) {
return ;
}
export function CustomVariants() {
return 自定义按钮;
}
```
### 添加涟漪效果
Button 组件支持通过组合方式实现涟漪效果，你可以将涟漪组件作为子节点嵌套。此示例使用 [m3-ripple](https://github.com/saltyaom/m3-ripple)。
```tsx
"use client";
import {Button} from "@heroui/react";
import {Ripple} from "m3-ripple";
import "m3-ripple/ripple.css";
export function RippleEffect() {
return (
);
}
```
### CSS 类
Button 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button.css)）：
#### 基础与尺寸类
- `.button` - 按钮基础样式
- `.button--sm` - 小尺寸变体
- `.button--md` - 中尺寸变体
- `.button--lg` - 大尺寸变体
#### 变体类
- `.button--primary`
- `.button--secondary`
- `.button--tertiary`
- `.button--outline`
- `.button--ghost`
- `.button--danger`
#### 修饰符类
- `.button--icon-only`
- `.button--icon-only.button--sm`
- `.button--icon-only.button--lg`
### 交互状态
该按钮同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制：
- **悬停**：`:hover` 或 `[data-hovered="true"]`
- **激活/按压**：`:active` 或 `[data-pressed="true"]`（包含缩放变换）
- **聚焦**：`:focus-visible` 或 `[data-focus-visible="true"]`（显示焦点环）
- **禁用**：`:disabled` 或 `[aria-disabled="true"]`（降低透明度，禁用指针事件）
- **等待中**：`[data-pending]`（加载期间禁用指针事件）
## API 参考
### Button Props
| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'outline' \| 'ghost' \| 'danger'` | `'primary'` | 视觉样式变体 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 按钮尺寸 |
| `fullWidth` | `boolean` | `false` | 按钮是否占满容器宽度 |
| `isDisabled` | `boolean` | `false` | 按钮是否禁用 |
| `isPending` | `boolean` | `false` | 按钮是否处于加载状态 |
| `isIconOnly` | `boolean` | `false` | 按钮是否仅包含图标 |
| `onPress` | `(e: PressEvent) => void` | - | 按钮被按下时的事件处理函数 |
| `children` | `React.ReactNode \| (values: ButtonRenderProps) => React.ReactNode` | - | 按钮内容或渲染 prop |
| `render` | `DOMRenderFunction` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|
### ButtonRenderProps
使用渲染 prop 模式时，会提供以下值：
| Prop | 类型 | 描述 |
|------|------|------|
| `isPending` | `boolean` | 按钮是否处于加载状态 |
| `isPressed` | `boolean` | 按钮当前是否被按压 |
| `isHovered` | `boolean` | 按钮是否处于悬停状态 |
| `isFocused` | `boolean` | 按钮是否处于聚焦状态 |
| `isFocusVisible` | `boolean` | 按钮是否应显示焦点指示 |
| `isDisabled` | `boolean` | 按钮是否禁用 |