Checkbox
@cloudflare/kumo

Checkbox

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

import { useState } from "react";
import { Checkbox } from "@cloudflare/kumo";

export function CheckboxBasicDemo() {
  const [checked, setChecked] = useState(false);
  return (
    <Checkbox
      label="Accept terms and conditions"
      checked={checked}
      onCheckedChange={setChecked}
    />
  );
}

安装

批量导入

import { Checkbox } from "@cloudflare/kumo";

按需导入

import { Checkbox } from "@cloudflare/kumo/components/checkbox";

用法

import { Checkbox } from "@cloudflare/kumo";

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

示例

默认

带内置标签的 Checkbox。标签会自动以水平布局显示（Checkbox 在标签之前）。

import { useState } from "react";
import { Checkbox } from "@cloudflare/kumo";

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

已选中

import { useState } from "react";
import { Checkbox } from "@cloudflare/kumo";

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

半选

用于”全选”模式中仅部分项目被选中的场景。

import { useState } from "react";
import { Checkbox } from "@cloudflare/kumo";

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

标签在前的布局

使用 controlFirst={false} 将标签放在 Checkbox 之前。

import { useState } from "react";
import { Checkbox } from "@cloudflare/kumo";

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

禁用

import { Checkbox } from "@cloudflare/kumo";

export function CheckboxDisabledDemo() {
  return <Checkbox label="Disabled option" disabled />;
}

错误

错误变体提供视觉样式（红色描边）。若需显示错误提示文本，请使用 Checkbox.Group。

import { Checkbox } from "@cloudflare/kumo";

export function CheckboxErrorDemo() {
  return <Checkbox label="Invalid option" variant="error" />;
}

Checkbox 分组

使用图例（legend）、描述和共享的错误提示消息将多个 Checkbox 归组。使用 Checkbox.Group 和 Checkbox.Item。

Email preferences

Choose how you'd like to receive updates

import { useState } from "react";
import { Checkbox } from "@cloudflare/kumo";

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

  return (
    <Checkbox.Group
      legend="Email preferences"
      description="Choose how you'd like to receive updates"
      value={preferences}
      onValueChange={setPreferences}
    >
      <Checkbox.Item value="email" label="Email notifications" />
      <Checkbox.Item value="sms" label="SMS notifications" />
      <Checkbox.Item value="push" label="Push notifications" />
    </Checkbox.Group>
  );
}

带错误的 Checkbox 分组

在分组级别显示校验错误。存在错误时，错误消息会替换描述。

Required preferences

Please select at least one notification method

import { Checkbox } from "@cloudflare/kumo";

export function CheckboxGroupErrorDemo() {
  return (
    <Checkbox.Group
      legend="Required preferences"
      error="Please select at least one notification method"
      value={[]}
      onValueChange={() => {}}
    >
      <Checkbox.Item value="email" label="Email" variant="error" />
      <Checkbox.Item value="sms" label="SMS" variant="error" />
    </Checkbox.Group>
  );
}

卡片式 Checkbox

在组上使用 appearance="card"，可将每个选项显示为单个卡片中可通过分隔线 分隔选择的行。可结合每个项目的 description 属性获得更丰富的内容。 卡片项目默认将 Checkbox 放在标签之后，除非设置了 controlFirst。

Where should this profile scan?
import { useState } from "react";
import { Checkbox } from "@cloudflare/kumo";

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

  return (
    <Checkbox.Group
      legend="Where should this profile scan?"
      appearance="card"
      value={products}
      onValueChange={setProducts}
    >
      <Checkbox.Item
        value="gateway"
        label="Web traffic"
        description="Uploads and downloads through Gateway HTTP policies."
      />
      <Checkbox.Item
        value="ai"
        label="AI prompts"
        description="Prompts sent to AI apps, and the responses they return."
      />
      <Checkbox.Item
        value="casb"
        label="SaaS and cloud storage"
        description="Files stored in connected apps and cloud accounts."
      />
      <Checkbox.Item
        value="email"
        label="Outbound email"
        description="Email leaving your organization."
      />
    </Checkbox.Group>
  );
}

卡片式 Checkbox（水平）

将 appearance="card" 与 orientation="horizontal" 结合，可将选项在同一个 卡片内排列成两列。

Where should this profile scan?
import { useState } from "react";
import { Checkbox } from "@cloudflare/kumo";

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

  return (
    <Checkbox.Group
      legend="Where should this profile scan?"
      appearance="card"
      orientation="horizontal"
      value={products}
      onValueChange={setProducts}
    >
      <Checkbox.Item
        value="gateway"
        label="Web traffic"
        description="Uploads and downloads through Gateway HTTP policies."
      />
      <Checkbox.Item
        value="ai"
        label="AI prompts"
        description="Prompts sent to AI apps, and the responses they return."
      />
      <Checkbox.Item
        value="casb"
        label="SaaS and cloud storage"
        description="Files stored in connected apps and cloud accounts."
      />
      <Checkbox.Item
        value="email"
        label="Outbound email"
        description="Email leaving your organization."
      />
    </Checkbox.Group>
  );
}

视觉隐藏的图例

使用 Checkbox.Legend 并搭配 className="sr-only"，可使图例保持对屏幕阅读器可用，同时在视觉上隐藏。当分组已由其父级 Field 或标题提供标签、显示图例会形成重复标签时，这一做法很有用。

Notification preferences
import { useState } from "react";
import { Checkbox } from "@cloudflare/kumo";

/** Shows Checkbox.Legend with sr-only to visually hide the legend while keeping it accessible, useful when a parent Field already provides a visible label */
export function CheckboxLegendSrOnlyDemo() {
  const [preferences, setPreferences] = useState<string[]>(["email"]);
  return (
    <Checkbox.Group value={preferences} onValueChange={setPreferences}>
      <Checkbox.Legend className="sr-only">
        Notification preferences
      </Checkbox.Legend>
      <Checkbox.Item value="email" label="Email notifications" />
      <Checkbox.Item value="sms" label="SMS notifications" />
      <Checkbox.Item value="push" label="Push notifications" />
    </Checkbox.Group>
  );
}

自定义图例样式

Checkbox.Legend 接受 className，可完全控制图例的呈现效果。当需要自定义排版、颜色或布局时，请用它替代 legend 字符串属性。

Notification preferences
import { useState } from "react";
import { Checkbox } from "@cloudflare/kumo";

/** Shows Checkbox.Legend with custom styling for full control over legend presentation */
export function CheckboxLegendCustomDemo() {
  const [preferences, setPreferences] = useState<string[]>(["email"]);
  return (
    <Checkbox.Group value={preferences} onValueChange={setPreferences}>
      <Checkbox.Legend className="text-sm font-normal text-kumo-subtle">
        Notification preferences
      </Checkbox.Legend>
      <Checkbox.Item value="email" label="Email notifications" />
      <Checkbox.Item value="sms" label="SMS notifications" />
      <Checkbox.Item value="push" label="Push notifications" />
    </Checkbox.Group>
  );
}

API 参考

Checkbox

带有内置标签和水平布局的单个 Checkbox 组件。

PropTypeDefaultDescription
variant"default" | "error""default"

视觉变体："default" 或 "error" 用于校验失败（仅视觉，无错误文本）

labelReactNode-

复选框的标签内容（启用内置 Field 包装器）- 可以是字符串或任何 React 节点

labelTooltipReactNode-

通过信息图标显示在标签旁边的 Tooltip 内容。

controlFirstboolean-

当 true（默认）时，复选框显示在标签前。当 false 时，标签显示在复选框前。

checkedboolean-

复选框是否被选中（受控）

indeterminateboolean-

复选框是否处于不确定状态

disabledboolean-

复选框是否被禁用

namestring-

表单提交时的名称

requiredboolean-

该字段是否为必填项

classNamestring-

额外的类名

Checkbox.Group

用于多个 Checkbox 的包装器，支持图例、描述和错误提示。

PropTypeDefaultDescription
legendstring-

分组的图例文本。若需更精细地控制图例样式，请省略此属性，改用 <Checkbox.Legend> 作为子元素。

children*ReactNode-

子 Checkbox.Item 组件（可选配 Checkbox.Legend）

errorstring-

组的错误消息（仅出现在组中，不适用于单个复选框）

descriptionReactNode-

组的帮助文本

valuestring[]-

应被选中的复选框的值（受控）

allValuesstring[]-

所有可能的复选框值（父复选框模式必填）

disabledboolean-

是否禁用组中的所有复选框

orientation"vertical" | "horizontal"-

校验框项目的布局方向。

appearanceKumoCheckboxAppearance-

应用于所有 Checkbox.Item 子元素的视觉外观。

  • "default" — 标准内联校验框项目
  • "card" — 带边框、内边距和突出选中状态的选择卡片 单个项目可通过自身的 appearance 属性覆盖此设置。
controlFirstboolean-

为 true 时，校验框出现在标签之前；为 false 时，标签出现在校验框之前。默认外观下默认为 true，卡片外观下默认为 false。

classNamestring-

额外的 CSS 类

Checkbox.Legend

Checkbox.Group 的可组合图例子组件。接受 className 以完全控制样式（例如使用 className="sr-only" 实现视觉隐藏）。当需要自定义图例样式时，用它替代 legend 字符串属性。

PropTypeDefaultDescription
children*ReactNode-

图例内容

classNamestring-

额外的 CSS 类（例如用 "sr-only" 视觉隐藏图例）

Checkbox.Item

Checkbox.Group 中的单个 Checkbox。

PropTypeDefault

No component-specific props. Accepts standard HTML attributes.

无障碍

标签要求

单个 Checkbox 必须提供 label 属性或 aria-label 才能保证无障碍访问。 缺少标签时，开发环境会在控制台输出警告。

键盘导航

空格切换 Checkbox 的选中状态。 Tab在 Checkbox 之间移动焦点。

屏幕阅读器

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