Button 按钮

引入

import { Button } from '@heroui/react';

用法

变体

带图标

仅图标

加载中

加载状态

尺寸

全宽

禁用状态

社交按钮

自定义渲染函数

样式

传入 Tailwind CSS 类

import { Button } from '@heroui/react';

function CustomButton() {
  return (
    <Button className="bg-purple-500 text-white hover:bg-purple-600">
      Purple Button
    </Button>
  );
}

自定义组件类

若要自定义 Button 组件类，可以使用 @layer components 指令。

了解更多。

@layer components {
  .button {
    @apply bg-purple-500 text-white hover:bg-purple-600;
  }

  .button--icon-only {
    @apply rounded-lg bg-blue-500;
  }
}

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

添加自定义变体

你可以通过封装 HeroUI 组件并添加自定义变体来扩展其能力。

添加涟漪效果

Button 组件支持通过组合方式实现涟漪效果，你可以将涟漪组件作为子节点嵌套。此示例使用 m3-ripple。

CSS 类

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<keyof React.JSX.IntrinsicElements, ButtonRenderProps>	-	使用自定义渲染函数覆盖默认 DOM 元素。

ButtonRenderProps

使用渲染 prop 模式时，会提供以下值：

Prop	类型	描述
isPending	boolean	按钮是否处于加载状态
isPressed	boolean	按钮当前是否被按压
isHovered	boolean	按钮是否处于悬停状态
isFocused	boolean	按钮是否处于聚焦状态
isFocusVisible	boolean	按钮是否应显示焦点指示
isDisabled	boolean	按钮是否禁用