Switch 开关
@lark-ui/core

Switch 开关

可以在开启和关闭两种状态之间切换的按钮。

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

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

安装

统一导出

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

按需导出

import { Switch } from "@lark-ui/core/components/switch";

用法

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

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

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

示例

关闭状态

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

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

开启状态

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

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

禁用

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

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

变体

开关（Switch）支持两种变体：default（开启时为蓝色）和 neutral（单色）。两者都使用 超椭圆（squircle）形状。

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

/** 所有变体对比——2×2 网格展示默认变体和中性变体的关闭/开启状态 */
export function SwitchVariantsDemo() {
  return (
    <div className="grid grid-cols-2 gap-x-8 gap-y-4">
      <Switch label="默认关闭" checked={false} onCheckedChange={() => {}} />
      <Switch label="默认开启" checked={true} onCheckedChange={() => {}} />
      <Switch
        label="中性关闭"
        variant="neutral"
        checked={false}
        onCheckedChange={() => {}}
      />
      <Switch
        label="中性开启"
        variant="neutral"
        checked={true}
        onCheckedChange={() => {}}
      />
    </div>
  );
}

中性变体

中性变体使用单色配色和超椭圆形状，适合低调、不突出的切换控件。

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

/** 中性变体——单色开关，适用于不显眼、弱化强调的切换 */
export function SwitchNeutralDemo() {
  const [checked, setChecked] = useState(false);
  return (
    <Switch
      label="中性开关"
      variant="neutral"
      checked={checked}
      onCheckedChange={setChecked}
    />
  );
}

中性状态

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

/** 中性变体的不同状态 */
export function SwitchNeutralStatesDemo() {
  return (
    <div className="flex flex-col gap-4">
      <Switch
        label="中性关闭"
        variant="neutral"
        checked={false}
        onCheckedChange={() => {}}
      />
      <Switch
        label="中性开启"
        variant="neutral"
        checked={true}
        onCheckedChange={() => {}}
      />
      <Switch label="中性禁用" variant="neutral" checked={false} disabled />
    </div>
  );
}

尺寸

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

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

/** 所有尺寸对比 */
export function SwitchSizesDemo() {
  return (
    <div className="flex flex-col gap-4">
      <Switch label="小" size="sm" checked={true} onCheckedChange={() => {}} />
      <Switch
        label="常规（默认）"
        size="base"
        checked={true}
        onCheckedChange={() => {}}
      />
      <Switch label="大" size="lg" checked={true} onCheckedChange={() => {}} />
    </div>
  );
}

自定义 ID

提供自定义 id 后，点击标签仍会切换开关状态。该 id 会透传给 Base UI，使标签的 htmlFor 保持同步。

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

/** 带自定义 id 属性的开关（Switch）——点击标签仍应能切换开关。 */
export function SwitchCustomIdDemo() {
  const [checked, setChecked] = useState(false);
  return (
    <Switch
      id="my-custom-switch"
      label="自定义 ID"
      checked={checked}
      onCheckedChange={setChecked}
    />
  );
}

开关组

使用 Switch.Group 可以对相关开关进行分组，并为分组提供共享的图例（legend）、描述和 错误信息。

通知设置
import { Switch } from "@lark-ui/core";

/** 展示带图例的 Switch.Group，用于对相关开关分组 */
export function SwitchGroupDemo() {
  return (
    <Switch.Group legend="通知设置">
      <Switch.Item label="邮件通知" />
      <Switch.Item label="短信通知" />
      <Switch.Item label="推送通知" />
    </Switch.Group>
  );
}

视觉隐藏的图例

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

通知设置
import { Switch } from "@lark-ui/core";

/** 展示使用 sr-only 的 Switch.Legend，在保留无障碍语义的同时视觉隐藏图例；当父级 Field 已提供可见标签时非常有用 */
export function SwitchLegendSrOnlyDemo() {
  return (
    <Switch.Group>
      <Switch.Legend className="sr-only">通知设置</Switch.Legend>
      <Switch.Item label="邮件通知" />
      <Switch.Item label="短信通知" />
      <Switch.Item label="推送通知" />
    </Switch.Group>
  );
}

自定义图例样式

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

通知设置
import { Switch } from "@lark-ui/core";

/** 展示使用自定义样式的 Switch.Legend，完全掌控图例的呈现方式 */
export function SwitchLegendCustomDemo() {
  return (
    <Switch.Group>
      <Switch.Legend className="text-sm font-normal text-lark-subtle">
        通知设置
      </Switch.Legend>
      <Switch.Item label="邮件通知" />
      <Switch.Item label="短信通知" />
      <Switch.Item label="推送通知" />
    </Switch.Group>
  );
}

API 参考

Switch

带内置标签的单个开关。

属性类型默认值说明
variant"default" | "neutral""default"视觉变体：“default”（胶囊形、品牌色）或“neutral”（方形圆角、单色）
labelReactNode-开关的标签内容（内置 Field 包裹层）——可以是字符串或任意 React 节点。单独用于纯视觉展示时可省略。
labelTooltipReactNode-通过信息图标显示在标签旁的工具提示内容
requiredboolean-开关是否必填。显式设为 false 时，在标签后显示“(optional)”文字。
controlFirstboolean-为 true（默认）时开关显示在标签之前；为 false 时标签显示在开关之前。
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-点击开关时的回调

Switch.Group

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

属性类型默认值说明
legendstring-分组标题文字。如需更多控制标题样式，请省略此属性，改用 `<Switch.Legend>` 作为子元素。
children*ReactNode-子级的 Switch.Item 组件（也可以包含 Switch.Legend）
errorstring-分组的错误信息（仅在分组中显示，单个开关不显示）
descriptionReactNode-分组的辅助说明文字
disabledboolean-分组内所有开关是否禁用
controlFirstboolean-为 true（默认）时开关显示在标签之前；为 false 时标签显示在开关之前。
classNamestring-额外的 CSS 类名

Switch.Legend

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

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

Switch.Item

Switch.Group 中的单个开关。

属性类型默认值

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