ProComponents, templates & AI tooling
HeroUI
27.7k
快速开始
组件
发布说明
迁移

Checkbox 复选框

复选框允许用户从多个独立选项中选择多项，或将单个独立选项标记为已选。

FigmaStorybookReact Aria源代码样式源代码

引入

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

用法

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

export function Basic() {
  return (
    <Checkbox id="basic-terms">

组件结构

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

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

export default () => (
  <Checkbox>
    <Checkbox.Control>
      <Checkbox.Indicator />  
    </Checkbox.Control>
    <Checkbox.Content>
      <Label />
      <Description /> {/* Optional */}
    </Checkbox.Content>
  </Checkbox>
);

禁用

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

export function Disabled() {
  return (
    <Checkbox isDisabled id="feature">

默认选中

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

export function DefaultSelected() {
  return (
    <Checkbox defaultSelected id="default-notifications">

受控

状态：已勾选

"use client";

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

不定状态

"use client";

import {Checkbox, Description, Label} from "@heroui/react";
import {useState} from "react";

带标签

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

export function WithLabel() {
  return (
    <Checkbox id="label-marketing">

带说明

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

export function WithDescription() {
  return (
    <Checkbox id="description-notifications">

渲染 props

"use client";

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

export function RenderProps() {

表单集成

"use client";

import {Button, Checkbox, Label} from "@heroui/react";
import React from "react";

无效

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

export function Invalid() {
  return (
    <Checkbox isInvalid id="agreement" name="agreement">

自定义指示器

"use client";

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

export function CustomIndicator() {

全圆角

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

export function FullRounded() {
  return (
    <div className="flex flex-col gap-6">

变体

Checkbox 支持两种视觉变体：

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

主要变体

次要变体

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

export function Variants() {
  return (
    <div className="flex flex-col gap-4">

自定义渲染函数

"use client";

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

export function CustomRenderFunction() {

样式

传入 Tailwind CSS 类

你可以单独定制各个 Checkbox：

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

function CustomCheckbox() {
  return (
    <Checkbox name="custom">
      <Checkbox.Control className="border-2 border-purple-500 data-[selected=true]:bg-purple-500">
        <Checkbox.Indicator className="text-white" />
      </Checkbox.Control>
      <Checkbox.Content>
        <Label>Custom Checkbox</Label>
      </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 flex flex-col gap-1;
  }
}

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

CSS 类

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

  • .checkbox - Checkbox 根容器
  • .checkbox__control - Checkbox 控件方框
  • .checkbox__indicator - Checkbox 勾选指示器
  • .checkbox__content - 可选内容容器

交互状态

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

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

API 参考

Checkbox Props

继承自 React Aria Checkbox。

Prop类型默认值描述
isSelectedbooleanfalseCheckbox 是否选中
defaultSelectedbooleanfalseCheckbox 默认是否选中（非受控）
isIndeterminatebooleanfalseCheckbox 是否处于不定状态
isDisabledbooleanfalseCheckbox 是否禁用
isInvalidbooleanfalseCheckbox 是否无效
isReadOnlybooleanfalseCheckbox 是否只读
variant"primary" | "secondary""primary"组件的视觉变体。primary 为默认带阴影样式。secondary 为弱强调、无阴影变体，适合用于 surface 上。
namestring-input 元素的 name，用于提交 HTML 表单
valuestring-input 元素的 value，用于提交 HTML 表单
onChange(isSelected: boolean) => void-Checkbox 值变化时调用
childrenReact.ReactNode | (values: CheckboxRenderProps) => React.ReactNode-Checkbox 内容或渲染 prop
renderDOMRenderFunction<keyof React.JSX.IntrinsicElements, CheckboxRenderProps>-通过自定义渲染函数覆盖默认的 DOM 元素。

CheckboxRenderProps

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

Prop类型描述
isSelectedbooleanCheckbox 当前是否选中
isIndeterminatebooleanCheckbox 是否处于不定状态
isHoveredbooleanCheckbox 是否处于悬停状态
isPressedbooleanCheckbox 当前是否处于按下状态
isFocusedbooleanCheckbox 是否聚焦
isFocusVisiblebooleanCheckbox 是否处于键盘可见焦点状态
isDisabledbooleanCheckbox 是否禁用
isReadOnlybooleanCheckbox 是否只读

Card 卡片

用于分组相关内容与操作的灵活容器组件。

CheckboxGroup 复选框组

用于管理多项复选框选择的 CheckboxGroup 组件。

本页目录

引入用法组件结构禁用默认选中受控不定状态带标签带说明渲染 props表单集成无效自定义指示器全圆角变体自定义渲染函数样式传入 Tailwind CSS 类自定义组件类CSS 类交互状态API 参考Checkbox PropsCheckboxRenderProps