ProComponents, templates & AI tooling
HeroUI
27.7k

CheckboxGroup 复选框组更新

用于管理多个复选框选择的复选框组组件

用法

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

组件结构

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

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

示例

表面样式

Surface 组件内使用时,请使用 variant="secondary" 以应用适合 Surface 背景的低强调变体。

禁用

半选状态

受控组件

表单校验

功能扩展示例

自定义指示器

渲染函数

自定义样式

Tailwind CSS

全局 CSS

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

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

样式参考

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

CSS 类

CheckboxGroup 组件使用以下 CSS 类(查看源码样式):

基础类

  • .checkbox-group - 复选框组根容器

API 参考

CheckboxGroup

继承自 React Aria CheckboxGroup

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

Render Props

使用 render prop 模式时,提供以下值:

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

相关组件

本页目录