Skip to content
Lenso UI

ToggleButton 切换按钮

用于在开启/关闭或已选中/未选中状态之间切换的交互式切换控件。

用法

import { ToggleButton } from '@lenso/ui';

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";
import { Heart } from "@gravity-ui/icons";import { ToggleButton } from "@lenso/ui";
export function Basic() {  return (    <ToggleButton>      <ToggleButton.Icon>        <Heart />      </ToggleButton.Icon>      Like    </ToggleButton>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

示例

变体

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac2), Apache-2.0.import { Heart } from "@gravity-ui/icons";import { ToggleButton } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { styles } from "./source.stylex";export function Variants() {  return (    <div {...stylex.props(styles.row)}>      <ToggleButton>        <ToggleButton.Icon>          <Heart />        </ToggleButton.Icon>        Default      </ToggleButton>      <ToggleButton variant="ghost">        <ToggleButton.Icon>          <Heart />        </ToggleButton.Icon>        Ghost      </ToggleButton>    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

仅图标

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac2), Apache-2.0.import { Bookmark, Heart } from "@gravity-ui/icons";import { ToggleButton } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { styles } from "./source.stylex";export function IconOnly() {  return (    <div {...stylex.props(styles.row)}>      <ToggleButton isIconOnly aria-label="Like">        <ToggleButton.Icon>          <Heart />        </ToggleButton.Icon>      </ToggleButton>      <ToggleButton isIconOnly aria-label="Bookmark" variant="ghost">        <ToggleButton.Icon>          <Bookmark />        </ToggleButton.Icon>      </ToggleButton>    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

尺寸

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac2), Apache-2.0.import { Heart } from "@gravity-ui/icons";import { ToggleButton } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { styles } from "./source.stylex";export function Sizes() {  return (    <div {...stylex.props(styles.column)}>      <div {...stylex.props(styles.row)}>        {(["sm", "md", "lg"] as const).map((size, index) => (          <ToggleButton key={size} size={size}>            <ToggleButton.Icon>              <Heart />            </ToggleButton.Icon>            {["Small", "Medium", "Large"][index]}          </ToggleButton>        ))}      </div>      <div {...stylex.props(styles.row)}>        {(["sm", "md", "lg"] as const).map((size) => (          <ToggleButton key={size} isIconOnly aria-label="Like" size={size}>            <ToggleButton.Icon>              <Heart />            </ToggleButton.Icon>          </ToggleButton>        ))}      </div>    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

禁用

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac2), Apache-2.0.import { Heart, HeartFill } from "@gravity-ui/icons";import { ToggleButton } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { styles } from "./source.stylex";export function Disabled() {  return (    <div {...stylex.props(styles.row)}>      <ToggleButton disabled>        <ToggleButton.Icon>          <Heart />        </ToggleButton.Icon>        Like      </ToggleButton>      <ToggleButton defaultPressed disabled>        <ToggleButton.Icon>          <HeartFill />        </ToggleButton.Icon>        Like      </ToggleButton>    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

受控组件

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac2), Apache-2.0.import { Heart, HeartFill } from "@gravity-ui/icons";import { ToggleButton } from "@lenso/ui";import { useState } from "react";import * as stylex from "@stylexjs/stylex";import { styles } from "./source.stylex";export function Controlled() {  const [selected, setSelected] = useState(false);  return (    <div {...stylex.props(styles.controlled)}>      <ToggleButton pressed={selected} onPressedChange={setSelected}>        <ToggleButton.Icon>{selected ? <HeartFill /> : <Heart />}</ToggleButton.Icon>        {selected ? "Liked" : "Like"}      </ToggleButton>      <p {...stylex.props(styles.muted)}>        Status:{" "}        <span {...stylex.props(styles.medium)}>{selected ? "Selected" : "Not selected"}</span>      </p>    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

自定义样式

Tailwind CSS

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac2), Apache-2.0.import { Heart } from "@gravity-ui/icons";import { ToggleButton } from "@lenso/ui";import { styles } from "./source.stylex";export function CustomStyles() {  return (    <ToggleButton xstyle={styles.custom}>      <ToggleButton.Icon xstyle={styles.icon}>        <Heart />      </ToggleButton.Icon>      Save article    </ToggleButton>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

全局 CSS

若要自定义组件类，可使用 @layer components 指令。了解更多。

@layer components {  .toggle-button {    @apply bg-purple-500 text-white;  }
  .toggle-button--icon-only {    @apply rounded-lg;  }}

样式参考

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

CSS 类

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

基础与尺寸类 [!toc]

  • .toggle-button - 切换按钮基础样式
  • .toggle-button--sm - 小尺寸变体
  • .toggle-button--md - 中尺寸变体（默认）
  • .toggle-button--lg - 大尺寸变体

变体类 [!toc]

  • .toggle-button--default - 默认变体（填充背景）
  • .toggle-button--ghost - 幽灵变体（透明背景）

修饰符类 [!toc]

  • .toggle-button--icon-only - 仅图标切换按钮
  • .toggle-button--icon-only.toggle-button--sm - 小尺寸仅图标
  • .toggle-button--icon-only.toggle-button--lg - 大尺寸仅图标

交互状态

该切换按钮同时支持 CSS 伪类与 data 属性，以便灵活控制状态：

  • 已选中：[data-selected="true"]（强调色背景与前景）
  • 悬停：:hover 或 [data-hovered="true"]
  • 激活/按下：:active 或 [data-pressed="true"]（包含缩放变换）
  • 聚焦：:focus-visible 或 [data-focus-visible="true"]（显示焦点环）
  • 禁用：:disabled 或 [aria-disabled="true"]（降低透明度，禁用指针事件）

API 参考

ToggleButton

继承自 React Aria ToggleButton。

Prop类型默认值描述
variant'default' | 'ghost''default'视觉样式变体
size'sm' | 'md' | 'lg''md'切换按钮尺寸
isIconOnlybooleanfalse按钮是否仅包含图标
isSelectedboolean-受控的已选中状态
defaultSelectedbooleanfalse默认已选中状态（非受控）
isDisabledbooleanfalse是否禁用切换按钮
onChange(isSelected: boolean) => void-已选中状态变化时调用的处理函数
onPress(e: PressEvent) => void-按钮按下时调用的处理函数
childrenReact.ReactNode | (values: ToggleButtonRenderProps) => React.ReactNode-按钮内容或渲染 prop

ToggleButtonRenderProps

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

Prop类型描述
isSelectedboolean按钮当前是否已选中
isPressedboolean按钮当前是否处于按下状态
isHoveredboolean按钮是否处于悬停状态
isFocusedboolean按钮是否处于聚焦状态
isFocusVisibleboolean按钮是否应显示焦点指示
isDisabledboolean按钮是否被禁用

相关组件

Button 按钮

可点击的按钮组件，支持多种变体与状态

Switch 开关

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

Checkbox 复选框

复选框允许用户从列表中选择多项，或标记单个项目为选中状态