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。标签自动采用水平布局 (复选框位于标签之前)。

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} 可将标签放在复选框之前。

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 分组

将多个复选框分组，支持图例、说明与共享的错误消息。使用 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 属性可展示更丰富的内容。卡片样式下复选框位于标签之后，除非设置了 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

带内置标签与水平布局的单个复选框组件。

属性类型默认值说明
variant"default" | "error""default"Visual variant: "default" or "error" for validation failures (visual only, no error text)
labelReactNode-Label content for the checkbox (enables built-in Field wrapper) - can be a string or any React node
labelTooltipReactNode-Tooltip content to display next to the label via an info icon
controlFirstboolean-When true (default), checkbox appears before label. When false, label appears before checkbox.
checkedboolean-Whether the checkbox is checked (controlled)
indeterminateboolean-Whether the checkbox is in indeterminate state
disabledboolean-Whether the checkbox is disabled
namestring-Name for form submission
requiredboolean-Whether the field is required
classNamestring-Additional class name

Checkbox.Group

包裹多个复选框的容器，支持图例、说明与错误提示。

属性类型默认值说明
legendstring-Legend text for the group. For more control over legend styling, omit this prop and use `<Checkbox.Legend>` as a child instead.
children*ReactNode-Child Checkbox.Item components (and optionally a Checkbox.Legend)
errorstring-Error message for the group (only appears in groups, not single checkboxes)
descriptionReactNode-Helper text for the group
valuestring[]-Values of checkboxes that should be checked (controlled)
allValuesstring[]-All possible checkbox values (required for parent checkbox pattern)
disabledboolean-Whether all checkboxes in the group are disabled
orientation"vertical" | "horizontal"-Layout direction of the checkbox items
appearanceKumoCheckboxAppearance-Visual appearance applied to all Checkbox.Item children. - `"default"` — Standard inline checkbox items - `"card"` — Choice card with border, padding, and highlighted selection state Individual items can override this with their own `appearance` prop.
controlFirstboolean-When true, checkbox appears before label. When false, label appears before checkbox. Defaults to true for default appearance and false for card appearance.
classNamestring-Additional CSS classes

Checkbox.Legend

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

属性类型默认值说明
children*ReactNode-Legend content
classNamestring-Additional CSS classes (e.g. "sr-only" to visually hide the legend)

Checkbox.Item

Checkbox.Group 中的单个复选框。

属性类型默认值

该组件没有专属属性,接受标准 HTML 属性。

无障碍

标签要求

出于无障碍考虑,单个复选框需要 label 属性或 aria-label。缺少标签时会在开发环境触发控制台警告。

键盘导航

Space 切换复选框状态。 Tab 在复选框之间移动焦点。

屏幕阅读器

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