Switch 开关

引入

import { Switch, SwitchGroup, Label } from '@heroui/react';

用法

组件结构

引入 Switch 组件，并通过点语法访问各部分。

import { Switch, Description, FieldError } from '@heroui/react';

export default () => (
  <Switch>
    <Switch.Content>
      <Switch.Control>
        <Switch.Thumb>
          <Switch.Icon /> {/* 可选 */}
        </Switch.Thumb>
      </Switch.Control>
      Label {/* 纯文本 —— 可点击的标签，同时作为无障碍名称 */}
    </Switch.Content>
    <Description /> {/* 可选 — 字段级帮助文本 */}
    <FieldError /> {/* 可选 — 校验错误信息 */}
  </Switch>
);

要对多个 Switch 进行分组，请使用 SwitchGroup 组件：

import { Switch, SwitchGroup, Label } from '@heroui/react';

export default () => (
  <SwitchGroup>
    <Switch>
      <Switch.Content>
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
        Option 1
      </Switch.Content>
    </Switch>
    <Switch>
      <Switch.Content>
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
        Option 2
      </Switch.Content>
    </Switch>
  </SwitchGroup>
);

禁用

默认选中

受控

无标签

尺寸

标签位置

带图标

带描述

分组

横向分组

Render Props

表单集成

自定义样式

自定义渲染函数

样式

传入 Tailwind CSS 类

你可以自定义各个 Switch：

import { Switch, Label } from '@heroui/react';

function CustomSwitch() {
  return (
    <Switch>
      {({isSelected}) => (
        <>
          <Switch.Control
            className={`h-[31px] w-[51px] bg-blue-500 ${isSelected ? "bg-cyan-500 shadow-[0_0_12px_rgba(6,182,212,0.5)]" : ""}`}
          >
            <Switch.Thumb
              className={`size-[27px] bg-white shadow-sm ${isSelected ? "translate-x-5 shadow-lg" : ""}`}
            />
          </Switch.Control>
          Custom Switch
        </>
      )}
    </Switch>
  );
}

或自定义 SwitchGroup 布局：

import { Switch, SwitchGroup, Label } from '@heroui/react';

function CustomSwitchGroup() {
  return (
    <SwitchGroup className="gap-8" orientation="horizontal">
      <Switch>
        <Switch.Content>
          <Switch.Control>
            <Switch.Thumb />
          </Switch.Control>
          Option 1
        </Switch.Content>
      </Switch>
      <Switch>
        <Switch.Content>
          <Switch.Control>
            <Switch.Thumb />
          </Switch.Control>
          Option 2
        </Switch.Content>
      </Switch>
    </SwitchGroup>
  );
}

自定义组件类

若要自定义 Switch 组件类，可以使用 @layer components 指令。

了解更多。

@layer components {
  .switch {
    @apply inline-flex gap-3 items-center;
  }

  .switch__control {
    @apply h-5 w-8 bg-gray-400 data-[selected=true]:bg-blue-500;
  }

  .switch__thumb {
    @apply bg-white shadow-sm;
  }

  .switch__content {
    @apply items-center gap-3;
  }

  .switch__icon {
    @apply h-3 w-3 text-current;
  }
}

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

Switch 类

Switch 组件使用以下 CSS 类（查看源码样式）：

• .switch - Switch 根容器（字段）
• .switch__content - 包裹控件与标签文本的可点击 label
• .switch__control - Switch 轨道
• .switch__thumb - 可移动的滑块
• .switch__icon - 滑块内可选图标
• .switch--sm - 小尺寸变体
• .switch--md - 中尺寸变体（默认）
• .switch--lg - 大尺寸变体

SwitchGroup 类

SwitchGroup 组件使用以下 CSS 类（查看源码样式）：

• .switch-group - Switch 组容器
• .switch-group__items - Switch 项容器
• .switch-group--horizontal - 横向布局
• .switch-group--vertical - 纵向布局（默认）

交互状态

该 Switch 同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制：

• 已选中：[data-selected="true"]（滑块位置与背景色变化）
• 悬停：:hover 或 [data-hovered="true"]（作用于 Switch.Control / 按钮）
• 聚焦：:focus-visible 或 [data-focus-visible="true"]（在按钮上显示轨道焦点环）
• 禁用：[data-disabled="true"]（降低透明度，包括帮助文本）
• 按压：:active 或 [data-pressed="true"]

API 参考

Switch Props

继承自 React Aria SwitchField。

Prop	类型	默认值	描述
size	'sm' | 'md' | 'lg'	'md'	Switch 尺寸。
isSelected	boolean	false	Switch 是否打开。
defaultSelected	boolean	false	默认是否打开（非受控）。
isDisabled	boolean	false	Switch 是否禁用。
isInvalid	boolean	false	Switch 是否无效。
isReadOnly	boolean	false	Switch 是否只读。
isRequired	boolean	false	Switch 是否必须打开。
validate	(value: boolean) => ValidationError | true | null | undefined	-	自定义校验函数。
validationBehavior	'native' | 'aria'	'native'	使用原生 HTML 校验或 ARIA 校验。
name	string	-	输入元素名称，用于提交 HTML 表单。
value	string	-	输入元素值，用于提交 HTML 表单。
onChange	(isSelected: boolean) => void	-	Switch 值变化时的事件处理函数。
onPress	(e: PressEvent) => void	-	Switch 被按下时的事件处理函数。
children	React.ReactNode | (values: SwitchFieldRenderProps) => React.ReactNode	-	Switch 内容或字段级渲染 prop。
render	DOMRenderFunction<keyof React.JSX.IntrinsicElements, SwitchFieldRenderProps>	-	使用自定义渲染函数覆盖默认 DOM 元素。

Switch.Content Props

包裹控件与标签文本的可点击 <label>。请把 Switch.Control 与 Label 放在它内部；Description/FieldError 作为 Switch.Content 的兄弟节点。对于没有标签的 switch，省略 Label 并在 Switch 上传入 aria-label。

Prop	类型	默认值	描述
children	React.ReactNode | (values: SwitchButtonRenderProps) => React.ReactNode	-	按钮内容（控件 + 标签），或按钮级渲染 prop
className	string | (values: SwitchButtonRenderProps) => string	-	应用到可点击 label 的类名

SwitchFieldRenderProps

在根 Switch 上使用渲染 prop 时，提供以下字段级值：

Prop	类型	描述
isSelected	boolean	Switch 当前是否打开。
isDisabled	boolean	Switch 是否禁用。
isReadOnly	boolean	Switch 是否只读。
isInvalid	boolean	Switch 是否无效。
isRequired	boolean	Switch 是否必填。
state	ToggleState	Switch 的状态。

SwitchButtonRenderProps

Switch.Control 使用按钮级渲染 prop（isHovered、isPressed、isFocusVisible 等）。将函数作为 Switch.Control 的子元素即可访问。

SwitchGroup Props

Prop	类型	默认值	描述
orientation	'horizontal' | 'vertical'	'vertical'	Switch 组方向。
children	React.ReactNode	-	要渲染的 Switch 项。
className	string	-	额外的 CSS 类。