For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/v/0.6.0/components/checkbox.md.
  • 简体中文
  • Checkbox 复选框

    用于从一组选项中选择多项。

    基础用法

    basic.tsx
    import { Checkbox, Space } from '@ifhover/leaf-ui';
    
    export function CheckboxBasic() {
      return (
        <Space wrap>
          <Checkbox defaultChecked>接收项目动态</Checkbox>
          <Checkbox>接收每周摘要</Checkbox>
          <Checkbox disabled>暂不可用</Checkbox>
          <Checkbox disabled defaultChecked>
            已锁定
          </Checkbox>
        </Space>
      );
    }
    

    全选与半选

    indeterminate 表示部分选中,用于汇总子选项。它只影响显示与辅助技术识别;全选和提交值由 checked 决定。

    已选择 1 项
    check-all.tsx
    import { Checkbox, Flex, Space, Text } from '@ifhover/leaf-ui';
    
    import { useState } from 'react';
    
    const options = ['设计更新', '产品动态', '每周摘要'];
    
    export function CheckboxCheckAll() {
      const [selected, setSelected] = useState<string[]>(['设计更新']);
      const allChecked = selected.length === options.length;
      return (
        <Space direction="vertical" align="stretch">
          <Checkbox
            checked={allChecked}
            indeterminate={selected.length > 0 && !allChecked}
            onChange={(event) => setSelected(event.target.checked ? [...options] : [])}
          >
            订阅全部
          </Checkbox>
          <Flex gap="md" align="center" wrap justify="center">
            {options.map((option) => (
              <Checkbox
                key={option}
                checked={selected.includes(option)}
                onChange={(event) =>
                  setSelected(
                    event.target.checked
                      ? [...selected, option]
                      : selected.filter((item) => item !== option),
                  )
                }
              >
                {option}
              </Checkbox>
            ))}
          </Flex>
          <Text tone="muted">已选择 {selected.length} 项</Text>
        </Space>
      );
    }
    

    扩展用法

    选择 1–2 个兴趣
    extensions.tsx
    import { CheckboxGroup } from '@ifhover/leaf-ui';
    
    export function ExtensionDemo() {
      return (
        <CheckboxGroup
          legend="选择 1–2 个兴趣"
          options={['设计', '开发', '摄影']}
          defaultValue={['设计']}
          minCount={1}
          maxCount={2}
        />
      );
    }
    

    卡片选项

    卡片整块可点击,适合包含图标和说明的选项。

    连接服务
    surfaces.tsx
    import { Checkbox, CheckboxGroup, Space } from '@ifhover/leaf-ui';
    
    import { HardDrive, Mail, MessageSquare } from 'lucide-react';
    
    export function CheckboxCards() {
      
      return (
        <Space direction="vertical" align="stretch">
          <CheckboxGroup
            variant="card"
            legend={'连接服务'}
            defaultValue={['mail']}
            options={[
              {
                value: 'mail',
                label: '邮件',
                description: '读取与整理邮件',
                icon: <Mail />,
              },
              {
                value: 'drive',
                label: '云端文件',
                description: '查找与整理文件',
                icon: <HardDrive />,
              },
              {
                value: 'chat',
                label: '团队沟通',
                description: '当前不可用',
                icon: <MessageSquare />,
                disabled: true,
              },
            ]}
          />
          <Checkbox
            variant="card"
            indeterminate
            description={'部分服务已启用'}
          >
            {'全部服务'}
          </Checkbox>
        </Space>
      );
    }
    

    成组选项

    相关选项共用边框和行分隔线;状态标签放在右侧。

    邮件权限
    surfaces.tsx
    import { CheckboxGroup, Tag } from '@ifhover/leaf-ui';
    
    export function CheckboxList() {
      
      return (
        <CheckboxGroup
          variant="list"
          legend={'邮件权限'}
          defaultValue={['read']}
          options={[
            { value: 'read', label: '读取邮件', description: 'mail.readonly' },
            {
              value: 'send',
              label: '发送邮件',
              description: 'mail.send',
              extra: (
                <Tag color="warning" size="sm">
                  {'需要审批'}
                </Tag>
              ),
            },
            {
              value: 'delete',
              label: '删除邮件',
              description: 'mail.modify',
              extra: <Tag size="sm">{'策略限制'}</Tag>,
              disabled: true,
            },
          ]}
        />
      );
    }
    

    Checkbox API

    属性类型默认值说明
    size'sm' | 'md' | 'lg''md'复选框尺寸
    variant'plain' | 'card''plain'普通选项或整块可点击的卡片选项。
    descriptionReactNode—补充说明。
    iconReactNode—图标内容。
    extraReactNode—补充状态文字或标签;不要放置交互控件。
    indeterminatebooleanfalse半选状态
    checkedboolean—受控选中状态 / 非受控初始状态
    defaultCheckedboolean—受控选中状态 / 非受控初始状态
    onChangeChangeEventHandler<HTMLInputElement>—值发生变化时调用。
    disabledbooleanfalse禁用交互。
    childrenReactNode—子内容;嵌套数据类型表示子节点。
    refRef<HTMLInputElement>—复选框引用

    name、value、required、form 等原生属性可直接使用。只有已勾选且未禁用的复选框参与原生表单提交。没有文字标签时必须提供 aria-label。className 与 style 作用于标签容器。

    类型

    可导入 CheckboxProps 定义组件属性,或使用尺寸类型:

    import type { CheckboxProps, ControlSize } from '@ifhover/leaf-ui';

    扩展类型

    import type { CheckboxGroupProps, CheckboxOption } from '@ifhover/leaf-ui';

    CheckboxGroupProps API

    属性类型默认值说明
    optionsreadonly (CheckboxOption | string)[]必填必需。可用选项
    valuereadonly string[]—受控值
    defaultValuereadonly string[][]初始值;非受控表单 reset 时恢复
    onChange(values: string[]) => void—值变化回调
    legendReactNode—字段组名称
    size'sm' | 'md' | 'lg'—尺寸或间距预设
    variant'plain' | 'card' | 'list''plain'普通排列、卡片网格或带分隔线的成组列表。
    minCountnumber0最少勾选数量
    maxCountnumberInfinity最多勾选或展示数量
    requiredboolean—要求整体值非空,复合控件只校验一次。
    direction'horizontal' | 'vertical''horizontal'排列方向或移动方向

    CheckboxOption API

    属性类型默认值说明
    valuestring必填必需。受控值
    labelReactNode必填必需。显示内容
    descriptionReactNode—补充说明。
    iconReactNode—图标内容。
    extraReactNode—补充状态文字或标签;不要放置交互控件。
    disabledboolean—禁用交互。

    外观与丰富内容

    Checkbox 的 variant="card" 让标签整体成为可点击卡片;CheckboxGroup 的 variant="card" 自动排列卡片,variant="list" 使用成组列表。description 与 extra 会作为辅助描述,icon 为装饰内容。extra 适合状态标签,不应包含按钮或链接。原生 name、value、form、表单重置与键盘操作保持可用。