Checkbox 复选框更新

引入

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

用法

组件结构

引入 Checkbox 后，可通过点语法访问各个部分。

import { Checkbox, Description, FieldError } from '@heroui/react';

export default () => (
  <Checkbox>
    <Checkbox.Content>
      <Checkbox.Control>
        <Checkbox.Indicator />
      </Checkbox.Control>
      Label {/* 纯文本 —— 可点击的标签，同时作为无障碍名称 */}
    </Checkbox.Content>
    <Description /> {/* 可选 — 字段级帮助文本 */}
    <FieldError /> {/* 可选 — 校验错误信息 */}
  </Checkbox>
);

禁用

默认选中

受控

不定状态

外部标签

带说明

渲染 props

表单集成

无效

自定义指示器

全圆角

变体

Checkbox 支持两种视觉变体：

• primary（默认）— 常规样式与默认背景，适用于大多数场景
• secondary — 弱强调变体，适合用于 Surface 等组件内部

自定义渲染函数

样式

传入 Tailwind CSS 类

你可以单独定制各个 Checkbox：

import { Checkbox, Label } from '@heroui/react';

function CustomCheckbox() {
  return (
    <Checkbox name="custom">
      <Checkbox.Content>
        <Checkbox.Control className="border-2 border-purple-500 data-[selected=true]:bg-purple-500">
          <Checkbox.Indicator className="text-white" />
        </Checkbox.Control>
        Custom Checkbox
      </Checkbox.Content>
    </Checkbox>
  );
}

自定义组件类

若要自定义 Checkbox 的组件类名，可使用 @layer components 指令。
了解更多。

@layer components {
  .checkbox {
    @apply inline-flex gap-3 items-center;
  }

  .checkbox__control {
    @apply size-5 border-2 border-gray-400 rounded data-[selected=true]:bg-blue-500 data-[selected=true]:border-blue-500;

    /* Animated background indicator */
    &::before {
      @apply bg-accent pointer-events-none absolute inset-0 z-0 origin-center scale-50 rounded-md opacity-0 content-[''];
      
      transition:
        scale 200ms linear,
        opacity 200ms linear,
        background-color 200ms ease-out;
    }

    /* Show indicator when selected */
    &[data-selected="true"]::before {
      @apply scale-100 opacity-100;
    }
  }

  .checkbox__indicator {
    @apply text-white;
  }

  .checkbox__content {
    @apply items-center gap-3;
  }
}

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

CSS 类

Checkbox 使用以下 CSS 类（查看源码样式）：

• .checkbox - Checkbox 根容器
• .checkbox__content - 包裹控件与标签文本的可点击 label
• .checkbox__control - Checkbox 控件方框
• .checkbox__indicator - Checkbox 勾选指示器

交互状态

Checkbox 同时支持 CSS 伪类与 data 属性，以获得更好的灵活性：

• 选中：[data-selected="true"] 或 [aria-checked="true"]（显示勾选与背景色变化）
• 不定：[data-indeterminate="true"]（以横线表示不定状态）
• 无效：[data-invalid="true"] 或 [aria-invalid="true"]（以危险色显示错误状态）
• 悬停：:hover 或 [data-hovered="true"]（交互状态在 Checkbox.Control / 按钮上）
• 焦点：:focus-visible 或 [data-focus-visible="true"]（显示焦点环，作用于按钮）
• 禁用：[data-disabled="true"]（降低透明度并禁用指针事件）
• 按下：:active 或 [data-pressed="true"]

API 参考

Checkbox Props

继承自 React Aria CheckboxField。

Checkbox.Content Props

包裹控件与标签文本的可点击 <label>。请把 Checkbox.Control 与 Label 放在它内部；Description/FieldError 作为 Checkbox.Content 的兄弟节点。对于没有标签的 checkbox，省略 Label 并在 Checkbox 上传入 aria-label。

CheckboxFieldRenderProps

在根 Checkbox 上使用渲染 prop 时，提供以下字段级值：

CheckboxButtonRenderProps

Checkbox.Control 与 Checkbox.Indicator 使用按钮级渲染 prop（isHovered、isPressed、isFocusVisible 等）。将函数作为 Checkbox.Control 或 Checkbox.Indicator 的子元素即可访问。