Checkbox 复选框
@lark-ui/core

Checkbox 复选框

允许用户在选中与未选中之间切换的控件，内置标签支持并自动采用水平布局。

import { useState } from "react";
import { Checkbox } from "@lark-ui/core";

export function CheckboxBasicDemo() {
  const [checked, setChecked] = useState(false);
  return (
    <Checkbox
      label="接受服务条款"
      checked={checked}
      onCheckedChange={setChecked}
    />
  );
}

安装

统一导出

import { Checkbox } from "@lark-ui/core";

按需导出

import { Checkbox } from "@lark-ui/core/components/checkbox";

用法

import { Checkbox } from "@lark-ui/core";

export default function Example() {
  return <Checkbox label="Accept terms" />;
}

示例

默认

带内置标签的复选框。标签会自动以水平布局展示（复选框在标签之前）。

import { useState } from "react";
import { Checkbox } from "@lark-ui/core";

export function CheckboxDefaultDemo() {
  const [checked, setChecked] = useState(false);
  return (
    <Checkbox label="启用通知" checked={checked} onCheckedChange={setChecked} />
  );
}

选中

import { useState } from "react";
import { Checkbox } from "@lark-ui/core";

export function CheckboxCheckedDemo() {
  const [checked, setChecked] = useState(true);
  return (
    <Checkbox label="我同意" checked={checked} onCheckedChange={setChecked} />
  );
}

半选

用于“全选”场景：部分（但不是全部）选项被选中时使用。

import { useState } from "react";
import { Checkbox } from "@lark-ui/core";

export function CheckboxIndeterminateDemo() {
  const [indeterminate, setIndeterminate] = useState(true);
  return (
    <Checkbox
      label="全选"
      indeterminate={indeterminate}
      onCheckedChange={setIndeterminate}
    />
  );
}

标签在前布局

使用 controlFirst={false} 可将标签放在复选框之前。

import { useState } from "react";
import { Checkbox } from "@lark-ui/core";

export function CheckboxLabelFirstDemo() {
  const [checked, setChecked] = useState(false);
  return (
    <Checkbox
      label="记住我"
      controlFirst={false}
      checked={checked}
      onCheckedChange={setChecked}
    />
  );
}

禁用

import { Checkbox } from "@lark-ui/core";

export function CheckboxDisabledDemo() {
  return <Checkbox label="禁用的选项" disabled />;
}

错误

错误变体提供视觉样式（红色描边）。如需展示错误信息，请使用 Checkbox.Group。

import { Checkbox } from "@lark-ui/core";

export function CheckboxErrorDemo() {
  return <Checkbox label="无效的选项" variant="error" />;
}

复选框组

通过图例、描述和共享的错误信息将多个复选框组织在一起。使用 Checkbox.Group 和 Checkbox.Item。

邮件通知偏好

选择你希望接收更新的方式

import { useState } from "react";
import { Checkbox } from "@lark-ui/core";

export function CheckboxGroupDemo() {
  const [preferences, setPreferences] = useState<string[]>(["email"]);

  return (
    <Checkbox.Group
      legend="邮件通知偏好"
      description="选择你希望接收更新的方式"
      value={preferences}
      onValueChange={setPreferences}
    >
      <Checkbox.Item value="email" label="邮件通知" />
      <Checkbox.Item value="sms" label="短信通知" />
      <Checkbox.Item value="push" label="推送通知" />
    </Checkbox.Group>
  );
}

带错误的复选框组

在组级别展示校验错误。存在错误信息时，错误会取代描述。

必填的通知方式

请至少选择一种通知方式

import { Checkbox } from "@lark-ui/core";

export function CheckboxGroupErrorDemo() {
  return (
    <Checkbox.Group
      legend="必填的通知方式"
      error="请至少选择一种通知方式"
      value={[]}
      onValueChange={() => {}}
    >
      <Checkbox.Item value="email" label="邮件" variant="error" />
      <Checkbox.Item value="sms" label="短信" variant="error" />
    </Checkbox.Group>
  );
}

复选框卡片

在组上使用 appearance="card"，可将每个选项显示为同一张卡片中的可选择行，各行之间以分隔线隔开。可为每个选项搭配 description 属性以承载更丰富的内容。除非设置了 controlFirst，卡片中的选项会将复选框放在标签之后。

此配置文件应扫描哪些内容？
import { useState } from "react";
import { Checkbox } from "@lark-ui/core";

export function CheckboxCardDemo() {
  const [products, setProducts] = useState<string[]>(["gateway"]);

  return (
    <Checkbox.Group
      legend="此配置文件应扫描哪些内容？"
      appearance="card"
      value={products}
      onValueChange={setProducts}
    >
      <Checkbox.Item
        value="gateway"
        label="Web 流量"
        description="通过 Gateway HTTP 策略进行的上传和下载。"
      />
      <Checkbox.Item
        value="ai"
        label="AI 提示词"
        description="发送给 AI 应用的提示词及其返回的响应。"
      />
      <Checkbox.Item
        value="casb"
        label="SaaS 与云存储"
        description="存储在已连接应用和云账户中的文件。"
      />
      <Checkbox.Item
        value="email"
        label="出站邮件"
        description="离开你所在组织的外发邮件。"
      />
    </Checkbox.Group>
  );
}

复选框卡片（横向）

将 appearance="card" 与 orientation="horizontal" 结合使用，可在同一张卡片内以两列排布选项。

此配置文件应扫描哪些内容？
import { useState } from "react";
import { Checkbox } from "@lark-ui/core";

export function CheckboxCardHorizontalDemo() {
  const [products, setProducts] = useState<string[]>(["gateway"]);

  return (
    <Checkbox.Group
      legend="此配置文件应扫描哪些内容？"
      appearance="card"
      orientation="horizontal"
      value={products}
      onValueChange={setProducts}
    >
      <Checkbox.Item
        value="gateway"
        label="Web 流量"
        description="通过 Gateway HTTP 策略进行的上传和下载。"
      />
      <Checkbox.Item
        value="ai"
        label="AI 提示词"
        description="发送给 AI 应用的提示词及其返回的响应。"
      />
      <Checkbox.Item
        value="casb"
        label="SaaS 与云存储"
        description="存储在已连接应用和云账户中的文件。"
      />
      <Checkbox.Item
        value="email"
        label="出站邮件"
        description="离开你所在组织的外发邮件。"
      />
    </Checkbox.Group>
  );
}

视觉隐藏的图例

为 Checkbox.Legend 加上 className="sr-only"，可以在视觉上隐藏图例的同时保持屏幕阅读器可访问。当分组已经由上层的 Field 或标题标注、显示图例会造成标签重复时，这样处理很合适。

通知偏好
import { useState } from "react";
import { Checkbox } from "@lark-ui/core";

/** 展示使用 sr-only 的 Checkbox.Legend，在保留无障碍语义的同时视觉隐藏图例；当父级 Field 已提供可见标签时非常有用 */
export function CheckboxLegendSrOnlyDemo() {
  const [preferences, setPreferences] = useState<string[]>(["email"]);
  return (
    <Checkbox.Group value={preferences} onValueChange={setPreferences}>
      <Checkbox.Legend className="sr-only">通知偏好</Checkbox.Legend>
      <Checkbox.Item value="email" label="邮件通知" />
      <Checkbox.Item value="sms" label="短信通知" />
      <Checkbox.Item value="push" label="推送通知" />
    </Checkbox.Group>
  );
}

自定义图例样式

Checkbox.Legend 支持 className，可完全控制图例的呈现方式。当需要自定义字体、颜色或布局时，请使用它而不是 legend 字符串属性。

通知偏好
import { useState } from "react";
import { Checkbox } from "@lark-ui/core";

/** 展示使用自定义样式的 Checkbox.Legend，完全掌控图例的呈现方式 */
export function CheckboxLegendCustomDemo() {
  const [preferences, setPreferences] = useState<string[]>(["email"]);
  return (
    <Checkbox.Group value={preferences} onValueChange={setPreferences}>
      <Checkbox.Legend className="text-sm font-normal text-lark-subtle">
        通知偏好
      </Checkbox.Legend>
      <Checkbox.Item value="email" label="邮件通知" />
      <Checkbox.Item value="sms" label="短信通知" />
      <Checkbox.Item value="push" label="推送通知" />
    </Checkbox.Group>
  );
}

API 参考

Checkbox

单个复选框组件，内置标签并采用水平布局。

属性类型默认值说明
variant"default" | "error""default"视觉变体：“default”，或在校验失败时使用“error”（仅视觉表现，不显示错误文字）
labelReactNode-复选框的标签内容（启用内置的 Field 包裹层）——可以是字符串或任意 React 节点
labelTooltipReactNode-通过信息图标显示在标签旁的工具提示内容
controlFirstboolean-为 true（默认）时复选框显示在标签之前；为 false 时标签显示在复选框之前。
checkedboolean-复选框是否选中（受控）
indeterminateboolean-复选框是否处于半选状态
disabledboolean-复选框是否禁用
namestring-表单提交使用的名称
requiredboolean-该字段是否必填
classNamestring-额外的类名

Checkbox.Group

用于容纳多个复选框的包装器，支持图例、描述和错误提示。

属性类型默认值说明
legendstring-分组标题文字。如需更多控制标题样式，请省略此属性，改用 `<Checkbox.Legend>` 作为子元素。
children*ReactNode-子级的 Checkbox.Item 组件（也可以包含 Checkbox.Legend）
errorstring-分组的错误信息（仅在分组中显示，单个复选框不显示）
descriptionReactNode-分组的辅助说明文字
valuestring[]-需要处于选中状态的复选框取值（受控）
allValuesstring[]-所有可选的复选框取值（父子复选框模式必填）
disabledboolean-分组内所有复选框是否禁用
orientation"vertical" | "horizontal"-复选项的排列方向
appearanceLarkCheckboxAppearance-应用到所有 Checkbox.Item 子元素的外观样式。- `"default"` — 标准行内复选项 - `"card"` — 带边框、内边距和高亮选中态的选项卡片 单个复选项可以用自己的 `appearance` 属性覆盖该样式。
controlFirstboolean-为 true 时复选框显示在标签之前；为 false 时标签显示在复选框之前。默认外观下为 true，卡片外观下为 false。
classNamestring-额外的 CSS 类名

Checkbox.Legend

Checkbox.Group 使用的可组合图例子组件。支持 className 以完全控制样式（例如 className="sr-only" 可视觉隐藏）。需要自定义图例样式时，请使用它而不是 legend 字符串属性。

属性类型默认值说明
children*ReactNode-标题内容
classNamestring-额外的 CSS 类名（例如用 “sr-only” 在视觉上隐藏标题）

Checkbox.Item

Checkbox.Group 中的单个复选框。

属性类型默认值

该组件没有专有属性，支持标准 HTML 属性。

无障碍

标签要求

单个复选框必须提供 label 属性或 aria-label 以满足无障碍要求。缺少标签时，开发环境会输出控制台警告。

键盘导航

Space 可切换 复选框的选中状态。 Tab 可在多个 复选框之间移动焦点。

屏幕阅读器

Checkbox.Group 使用语义化的 <fieldset> 和 <legend> 元素，以便正确播报分组信息。