Checkbox

Accept terms and conditions

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 在标签之前）。

Enable notifications

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}
    />
  );
}

已选中

I agree

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} />
  );
}

半选

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

Select all

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 之前。

Remember me

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}
    />
  );
}

禁用

Disabled option

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

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

错误

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

Invalid option

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

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

Checkbox 分组

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

Email preferences

Email notificationsSMS notificationsPush notifications

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

EmailSMS

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

Email notificationsSMS notificationsPush notifications

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

Email notificationsSMS notificationsPush notifications

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 组件。

Prop	Type	Default	Description
variant	`"default" \| "error"`	`"default"`	Visual variant: "default" or "error" for validation failures (visual only, no error text)
label	`ReactNode`	-	Label content for the checkbox (enables built-in Field wrapper) - can be a string or any React node
labelTooltip	`ReactNode`	-	Tooltip content to display next to the label via an info icon
controlFirst	`boolean`	-	When true (default), checkbox appears before label. When false, label appears before checkbox.
checked	`boolean`	-	Whether the checkbox is checked (controlled)
indeterminate	`boolean`	-	Whether the checkbox is in indeterminate state
disabled	`boolean`	-	Whether the checkbox is disabled
name	`string`	-	Name for form submission
required	`boolean`	-	Whether the field is required
className	`string`	-	Additional class name

Checkbox.Group

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

Prop	Type	Default	Description
legend	`string`	-	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)
error	`string`	-	Error message for the group (only appears in groups, not single checkboxes)
description	`ReactNode`	-	Helper text for the group
value	`string[]`	-	Values of checkboxes that should be checked (controlled)
allValues	`string[]`	-	All possible checkbox values (required for parent checkbox pattern)
disabled	`boolean`	-	Whether all checkboxes in the group are disabled
controlFirst	`boolean`	-	When true (default), checkbox appears before label. When false, label appears before checkbox.
className	`string`	-	Additional CSS classes

Checkbox.Legend

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

Prop	Type	Default	Description
children*	`ReactNode`	-	Legend content
className	`string`	-	Additional CSS classes (e.g. "sr-only" to visually hide the legend)

Checkbox.Item

Checkbox.Group 中的单个 Checkbox。

Prop	Type	Default

No component-specific props. Accepts standard HTML attributes.

无障碍

标签要求

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

键盘导航

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

屏幕阅读器

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