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
| Prop | 类型 | 默认值 | 描述 |
|---|---|---|---|
value | string[] | - | 当前选中值(受控) |
defaultValue | string[] | - | 默认选中值(非受控) |
onChange | (value: string[]) => void | - | 选中值变化时的回调 |
isDisabled | boolean | false | 是否禁用 |
isRequired | boolean | false | 是否必填 |
isReadOnly | boolean | false | 是否只读 |
isInvalid | boolean | false | 是否处于无效状态 |
name | string | - | 提交 HTML 表单时复选框组的名称 |
children | React.ReactNode | (values: CheckboxGroupRenderProps) => React.ReactNode | - | 内容或 render prop |
render | DOMRenderFunction<keyof React.JSX.IntrinsicElements, CheckboxGroupRenderProps> | - | 使用自定义 render 函数覆盖默认 DOM 元素 |
Render Props
使用 render prop 模式时,提供以下值:
| Prop | 类型 | 描述 |
|---|---|---|
value | string[] | 当前选中值 |
isDisabled | boolean | 是否禁用 |
isReadOnly | boolean | 是否只读 |
isInvalid | boolean | 是否处于无效状态 |
isRequired | boolean | 是否必填 |





