Switch
@cloudflare/kumo

Switch

一个可以在开、关两种状态之间切换的按钮。

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

export function SwitchBasicDemo() {
  const [checked, setChecked] = useState(false);
  return (
    <Switch label="Switch" checked={checked} onCheckedChange={setChecked} />
  );
}

安装

批量导入

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

细粒度导入

import { Switch } from "@cloudflare/kumo/components/switch";

用法

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

export default function Example() {
  const [checked, setChecked] = useState(false);

  return (
    <Switch checked={checked} onCheckedChange={(val) => setChecked(val)} />
  );
}

示例

关闭状态

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

export function SwitchOffDemo() {
  return <Switch label="Switch" checked={false} onCheckedChange={() => {}} />;
}

开启状态

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

export function SwitchOnDemo() {
  return <Switch label="Switch" checked={true} onCheckedChange={() => {}} />;
}

禁用

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

export function SwitchDisabledDemo() {
  return <Switch label="Disabled" checked={false} disabled />;
}

变体

Switch 支持两种变体：default（开启时为蓝色）和 neutral （单色）。两者都采用圆角方块（squircle）形状。

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

/** All variants comparison — 2×2 grid showing off/on for default and neutral */
export function SwitchVariantsDemo() {
  return (
    <div className="grid grid-cols-2 gap-x-8 gap-y-4">
      <Switch label="Default off" checked={false} onCheckedChange={() => {}} />
      <Switch label="Default on" checked={true} onCheckedChange={() => {}} />
      <Switch
        label="Neutral off"
        variant="neutral"
        checked={false}
        onCheckedChange={() => {}}
      />
      <Switch
        label="Neutral on"
        variant="neutral"
        checked={true}
        onCheckedChange={() => {}}
      />
    </div>
  );
}

中性变体

中性变体使用单色配色和圆角方块形状，适合低调、不显眼的开关。

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

/** Neutral variant - monochrome switch for subtle, less prominent toggles */
export function SwitchNeutralDemo() {
  const [checked, setChecked] = useState(false);
  return (
    <Switch
      label="Neutral switch"
      variant="neutral"
      checked={checked}
      onCheckedChange={setChecked}
    />
  );
}

中性状态

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

/** Neutral variant in different states */
export function SwitchNeutralStatesDemo() {
  return (
    <div className="flex flex-col gap-4">
      <Switch
        label="Neutral off"
        variant="neutral"
        checked={false}
        onCheckedChange={() => {}}
      />
      <Switch
        label="Neutral on"
        variant="neutral"
        checked={true}
        onCheckedChange={() => {}}
      />
      <Switch
        label="Neutral disabled"
        variant="neutral"
        checked={false}
        disabled
      />
    </div>
  );
}

尺寸

提供三种尺寸：sm、base（默认）和 lg。

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

/** All sizes comparison */
export function SwitchSizesDemo() {
  return (
    <div className="flex flex-col gap-4">
      <Switch
        label="Small"
        size="sm"
        checked={true}
        onCheckedChange={() => {}}
      />
      <Switch
        label="Base (default)"
        size="base"
        checked={true}
        onCheckedChange={() => {}}
      />
      <Switch
        label="Large"
        size="lg"
        checked={true}
        onCheckedChange={() => {}}
      />
    </div>
  );
}

自定义 ID

提供自定义 id 时，点击标签仍然可以切换开关。id 会转发给 Base UI，使标签的 htmlFor 保持同步。

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

/** Switch with a custom id prop — clicking the label should still toggle the switch. */
export function SwitchCustomIdDemo() {
  const [checked, setChecked] = useState(false);
  return (
    <Switch
      id="my-custom-switch"
      label="Custom ID"
      checked={checked}
      onCheckedChange={setChecked}
    />
  );
}

Switch 分组

使用 Switch.Group 把相关的开关归为一组。它为整组提供共用的图例、描述和错误信息。

Notification settings
import { Switch } from "@cloudflare/kumo";

/** Shows a Switch.Group with a legend for grouping related switches */
export function SwitchGroupDemo() {
  return (
    <Switch.Group legend="Notification settings">
      <Switch.Item label="Email notifications" />
      <Switch.Item label="SMS notifications" />
      <Switch.Item label="Push notifications" />
    </Switch.Group>
  );
}

视觉隐藏的图例

给 Switch.Legend 加上 className="sr-only"，可以让图例对屏幕阅读器保持可访问，同时在视觉上隐藏。当分组已由父级 Field 或标题标注、显示图例会造成重复标签时，这样处理很有用。

Notification settings
import { Switch } from "@cloudflare/kumo";

/** Shows Switch.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 SwitchLegendSrOnlyDemo() {
  return (
    <Switch.Group>
      <Switch.Legend className="sr-only">Notification settings</Switch.Legend>
      <Switch.Item label="Email notifications" />
      <Switch.Item label="SMS notifications" />
      <Switch.Item label="Push notifications" />
    </Switch.Group>
  );
}

自定义图例样式

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

Notification settings
import { Switch } from "@cloudflare/kumo";

/** Shows Switch.Legend with custom styling for full control over legend presentation */
export function SwitchLegendCustomDemo() {
  return (
    <Switch.Group>
      <Switch.Legend className="text-sm font-normal text-kumo-subtle">
        Notification settings
      </Switch.Legend>
      <Switch.Item label="Email notifications" />
      <Switch.Item label="SMS notifications" />
      <Switch.Item label="Push notifications" />
    </Switch.Group>
  );
}

API 参考

Switch

带内置标签的单个开关。

属性类型默认值说明
variant"default" | "neutral""default"Visual variant: "default" (pill, brand color) or "neutral" (squircle, monochrome)
labelReactNode-Label content for the switch (Field wrapper is built-in) - can be a string or any React node. Optional when used standalone for visual-only purposes.
labelTooltipReactNode-Tooltip content to display next to the label via an info icon
requiredboolean-Whether the switch is required. When explicitly false, shows "(optional)" text after the label.
controlFirstboolean-When true (default), switch appears before label. When false, label appears before switch.
size"sm" | "base" | "lg""base"-
checkedboolean--
disabledboolean--
transitioningboolean--
namestring--
type"submit" | "reset" | "button"--
valuestring | string[] | number--
classNamestring--
idstring--
langstring--
titlestring--
onClick*(event: React.MouseEvent) => void-Callback when switch is clicked

Switch.Group

多个开关的容器，支持图例、描述和错误信息。

属性类型默认值说明
legendstring-Legend text for the group. For more control over legend styling, omit this prop and use `<Switch.Legend>` as a child instead.
children*ReactNode-Child Switch.Item components (and optionally a Switch.Legend)
errorstring-Error message for the group (only appears in groups, not single switches)
descriptionReactNode-Helper text for the group
disabledboolean-Whether all switches in the group are disabled
controlFirstboolean-When true (default), switch appears before label. When false, label appears before switch.
classNamestring-Additional CSS classes

Switch.Legend

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

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

Switch.Item

Switch.Group 中的单个开关。

属性类型默认值

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