ProComponents, templates & AI tooling
HeroUI
27.7k
快速开始
组件
发布说明
迁移

Switch 开关

用于布尔状态的开关组件。

FigmaStorybookReact Aria源代码样式源代码

引入

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

用法

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

export function Basic() {
  return (
    <Switch>

组件结构

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

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

export default () => (
  <Switch>
    <Switch.Control>
      <Switch.Thumb>
        <Switch.Icon/> {/* Optional */}
      </Switch.Thumb>
    </Switch.Control>
    <Switch.Content>
      <Label />
      <Description /> {/* Optional */}
    </Switch.Content>
  </Switch>
);

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

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

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

禁用

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

export function Disabled() {
  return (
    <Switch isDisabled>

默认选中

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

export function DefaultSelected() {
  return (
    <Switch defaultSelected>

受控

开关已关闭

"use client";

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

无标签

import {Switch} from "@heroui/react";

export function WithoutLabel() {
  return (
    <Switch aria-label="启用通知">

尺寸

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

export function Sizes() {
  return (
    <div className="flex gap-6">

标签位置

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

export function LabelPosition() {
  return (
    <div className="flex flex-col gap-4">

带图标

"use client";

import {
  BellFill,
  BellSlash,

带描述

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

export function WithDescription() {
  return (
    <div className="max-w-sm">

分组

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

export function Group() {
  return (
    <SwitchGroup>

横向分组

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

export function GroupHorizontal() {
  return (
    <SwitchGroup className="overflow-x-auto" orientation="horizontal">

Render Props

"use client";

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

export function RenderProps() {

表单集成

"use client";

import {Button, Label, Switch, SwitchGroup} from "@heroui/react";
import React from "react";

自定义样式

"use client";

import {Check, Power} from "@gravity-ui/icons";
import {Switch} from "@heroui/react";

自定义渲染函数

"use client";

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

export function CustomRenderFunction() {

样式

传入 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>
          <Label>Custom Switch</Label>
        </>
      )}
    </Switch>
  );
}

或自定义 SwitchGroup 布局：

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

function CustomSwitchGroup() {
  return (
    <SwitchGroup className="gap-8" orientation="horizontal">
      <Switch>
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
        <Label>Option 1</Label>
      </Switch>
      <Switch>
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
        <Label>Option 2</Label>
      </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 flex flex-col gap-1;
  }

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

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

CSS 类

Switch 类

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

  • .switch - Switch 根容器
  • .switch__content - 可选内容容器
  • .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"]
  • 聚焦：:focus-visible 或 [data-focus-visible="true"]（显示焦点环）
  • 禁用：:disabled 或 [aria-disabled="true"]（降低透明度，禁用指针事件）
  • 按压：:active 或 [data-pressed="true"]

API 参考

Switch Props

继承自 React Aria Switch。

Prop类型默认值描述
size'sm' | 'md' | 'lg''md'Switch 尺寸。
isSelectedbooleanfalseSwitch 是否打开。
defaultSelectedbooleanfalse默认是否打开（非受控）。
isDisabledbooleanfalseSwitch 是否禁用。
namestring-输入元素名称，用于提交 HTML 表单。
valuestring-输入元素值，用于提交 HTML 表单。
onChange(isSelected: boolean) => void-Switch 值变化时的事件处理函数。
onPress(e: PressEvent) => void-Switch 被按下时的事件处理函数。
childrenReact.ReactNode | (values: SwitchRenderProps) => React.ReactNode-Switch 内容或渲染 prop。
renderDOMRenderFunction<keyof React.JSX.IntrinsicElements, SwitchRenderProps>-使用自定义渲染函数覆盖默认 DOM 元素。

SwitchRenderProps

使用渲染 prop 模式时，会提供以下值：

Prop类型描述
isSelectedbooleanSwitch 当前是否打开。
isHoveredbooleanSwitch 是否处于悬停状态。
isPressedbooleanSwitch 当前是否被按压。
isFocusedbooleanSwitch 是否聚焦。
isFocusVisiblebooleanSwitch 是否处于键盘聚焦状态。
isDisabledbooleanSwitch 是否禁用。
isReadOnlybooleanSwitch 是否只读。
state-Switch 的状态。

SwitchGroup Props

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

Surface 表面

提供表面级样式与子组件上下文的容器组件。

Table 表格

表格以行和列展示结构化数据，支持排序、选择、列宽调整与无限滚动。

本页目录

引入用法组件结构禁用默认选中受控无标签尺寸标签位置带图标带描述分组横向分组Render Props表单集成自定义样式自定义渲染函数样式传入 Tailwind CSS 类自定义组件类CSS 类Switch 类SwitchGroup 类交互状态API 参考Switch PropsSwitchRenderPropsSwitchGroup Props