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

CheckboxGroup 复选框组更新

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

StorybookReact Aria源代码样式源代码

引入

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

用法

组件结构

导入 CheckboxGroup 组件，并通过点语法访问所有子部分。

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

export default () => (
  <CheckboxGroup name="interests">
    <Label />
    <Description /> {/* Optional */}
    <Checkbox value="option1">
      <Checkbox.Content>
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
        Label {/* 纯文本 —— 可点击的标签 */}
      </Checkbox.Content>
      <Description /> {/* 可选：单个复选框的帮助文本 */}
    </Checkbox>
    <FieldError /> {/* Optional */}
  </CheckboxGroup>
);

在 Surface 内

置于 Surface 中时，使用 variant="secondary"，以应用适合表面背景的低强调变体。

自定义指示器

不定状态

受控

校验

禁用

特性与附加示例

自定义渲染函数

样式

传入 Tailwind CSS 类

你可以自定义 CheckboxGroup 组件：

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

function CustomCheckboxGroup() {
  return (
    <CheckboxGroup className="gap-4" name="custom">
      <Checkbox value="option1">
        <Checkbox.Content>
          <Checkbox.Control className="border-2 border-purple-500 data-[selected=true]:bg-purple-500">
            <Checkbox.Indicator className="text-white" />
          </Checkbox.Control>
          Option 1
        </Checkbox.Content>
      </Checkbox>
    </CheckboxGroup>
  );
}

自定义组件类

若要自定义 CheckboxGroup 组件类，可以使用 @layer components 指令。
了解更多.

@layer components {
  .checkbox-group {
    @apply flex flex-col gap-2;
  }
}

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

CSS 类

CheckboxGroup 组件使用以下 CSS 类（查看源码样式）：

  • .checkbox-group - 复选框组合容器基础样式

API 参考

CheckboxGroup Props

继承自 React Aria CheckboxGroup。

Prop类型默认值描述
valuestring[]-当前选中值（受控）
defaultValuestring[]-默认选中值（非受控）
onChange(value: string[]) => void-选中值变化时调用的处理函数
isDisabledbooleanfalse是否禁用整个复选框组合
isRequiredbooleanfalse是否必填
isReadOnlybooleanfalse是否只读
isInvalidbooleanfalse是否处于无效状态
namestring-提交 HTML 表单时复选框组合的名称
childrenReact.ReactNode | (values: CheckboxGroupRenderProps) => React.ReactNode-复选框组合内容或渲染 prop
renderDOMRenderFunction<keyof React.JSX.IntrinsicElements, CheckboxGroupRenderProps>-通过自定义渲染函数覆盖默认的 DOM 元素。

CheckboxGroupRenderProps

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

Prop类型描述
valuestring[]当前选中值
isDisabledboolean是否禁用
isReadOnlyboolean是否只读
isInvalidboolean是否处于无效状态
isRequiredboolean是否必填

Checkbox 复选框

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

Chip 标签

用于展示标签、状态与分类等信息的小型徽标。

本页目录

引入用法组件结构在 Surface 内自定义指示器不定状态受控校验禁用特性与附加示例自定义渲染函数样式传入 Tailwind CSS 类自定义组件类CSS 类API 参考CheckboxGroup PropsCheckboxGroupRenderProps