Toggle

toggle

切换按钮 · Base UI pressed 态 + ToggleGroup 单/多选

用法

基础用法

单个 Toggle 是可切换的按下态按钮，defaultPressed 设初始选中。

tsx

<>
  <Toggle aria-label="加粗"><Bold className="size-4" /></Toggle>
  <Toggle defaultPressed aria-label="加粗"><Bold className="size-4" /></Toggle>
</>

单选组

ToggleGroup 默认互斥单选，适合对齐方式这类切换。

tsx

<ToggleGroup defaultValue={["center"]}>
  <Toggle value="left" aria-label="左对齐"><AlignLeft className="size-4" /></Toggle>
  <Toggle value="center" aria-label="居中"><AlignCenter className="size-4" /></Toggle>
  <Toggle value="right" aria-label="右对齐"><AlignRight className="size-4" /></Toggle>
</ToggleGroup>

多选组

加 multiple 让组内多项可同时按下，适合富文本样式。

tsx

<ToggleGroup multiple defaultValue={["bold", "italic"]}>
  <Toggle value="bold" aria-label="加粗"><Bold className="size-4" /></Toggle>
  <Toggle value="italic" aria-label="斜体"><Italic className="size-4" /></Toggle>
  <Toggle value="underline" aria-label="下划线"><Underline className="size-4" /></Toggle>
</ToggleGroup>

变体

default 软底 / outline 主色实心 / pill 圆角 chip（AI 工具栏开关风）。

tsx

<>
  <Toggle defaultPressed aria-label="default"><Bold className="size-4" /></Toggle>
  <Toggle variant="outline" defaultPressed aria-label="outline"><Bold className="size-4" /></Toggle>
  <Toggle variant="pill" size="sm" defaultPressed aria-label="深度思考">
    <Sparkles className="size-3.5" /> 深度思考
  </Toggle>
</>

禁用

disabled 锁定按钮，按下态也可禁用。

tsx

<Toggle disabled defaultPressed aria-label="加粗"><Bold className="size-4" /></Toggle>

何时用

带按下态的图标/文字按钮（工具栏加粗、对齐、AI 工具栏「深度思考」开关）用 Toggle；多个 Toggle 互斥单选或多选共存用 ToggleGroup。语义是「开关一个设置」而非「按钮态」时用 Switch；纯单选一组对等选项用 Radio。

导入

import { Toggle, ToggleGroup, toggleVariants } from "@hulianui/ui"

Props

Toggle

名称	类型	默认	说明
pressed	`boolean`	—	受控按下态
defaultPressed	`boolean`	`false`	非受控初始按下态
disabled	`boolean`	`false`	禁用
value	`string`	—	在 ToggleGroup 内标识该项
variant	`"default"｜"outline"｜"pill"`	`"default"`	default=灰底软选中 / outline=主色实心 / pill=圆角描边 + soft 主色选中（AI 工具栏开关风）
size	`"sm"｜"md"`	`"md"`	—
className	`string`	—	—
aria-label	`string`	—	仅图标时必填

ToggleGroup

名称	类型	默认	说明
value	`string[]`	—	受控：已按下项 value 数组
defaultValue	`string[]`	—	非受控初始按下项数组
disabled	`boolean`	`false`	整组禁用
multiple	`boolean`	`false`	true=多选共存；false=单选互斥
orientation	`"horizontal"｜"vertical"`	`"horizontal"`	—
className	`string`	—	—

Events

Toggle

事件	类型	说明
onPressedChange	`(pressed: boolean) => void`	按下态变化（瑚琏收敛签名，丢 Base UI eventDetails）

ToggleGroup

事件	类型	说明
onValueChange	`(value: string[]) => void`	变化回调

Slots

Toggle

插槽	类型	说明
children	`ReactNode`	图标 / 文字

ToggleGroup

插槽	类型	说明
children	`ReactNode`	内放 `Toggle` 项

禁忌 / 坑

即便在 ToggleGroup 内，选中态也以 value 数组管理——multiple={false} 时数组里只会有 0 或 1 个元素。
仅渲染图标（无文字）的 Toggle 必须给 aria-label，否则读屏无名。
用 pressed/onPressedChange（或 group 的 value/onValueChange）即受控，须自管 state；非受控只给 defaultPressed/defaultValue。

Playground

variantdisabled

<Toggle>
  <Bold />
</Toggle>

用法

基础用法

单个 Toggle 是可切换的按下态按钮，defaultPressed 设初始选中。

tsx

<>
  <Toggle aria-label="加粗"><Bold className="size-4" /></Toggle>
  <Toggle defaultPressed aria-label="加粗"><Bold className="size-4" /></Toggle>
</>

单选组

ToggleGroup 默认互斥单选，适合对齐方式这类切换。

tsx

<ToggleGroup defaultValue={["center"]}>
  <Toggle value="left" aria-label="左对齐"><AlignLeft className="size-4" /></Toggle>
  <Toggle value="center" aria-label="居中"><AlignCenter className="size-4" /></Toggle>
  <Toggle value="right" aria-label="右对齐"><AlignRight className="size-4" /></Toggle>
</ToggleGroup>

多选组

加 multiple 让组内多项可同时按下，适合富文本样式。

tsx

<ToggleGroup multiple defaultValue={["bold", "italic"]}>
  <Toggle value="bold" aria-label="加粗"><Bold className="size-4" /></Toggle>
  <Toggle value="italic" aria-label="斜体"><Italic className="size-4" /></Toggle>
  <Toggle value="underline" aria-label="下划线"><Underline className="size-4" /></Toggle>
</ToggleGroup>

变体

default 软底 / outline 主色实心 / pill 圆角 chip（AI 工具栏开关风）。

tsx

<>
  <Toggle defaultPressed aria-label="default"><Bold className="size-4" /></Toggle>
  <Toggle variant="outline" defaultPressed aria-label="outline"><Bold className="size-4" /></Toggle>
  <Toggle variant="pill" size="sm" defaultPressed aria-label="深度思考">
    <Sparkles className="size-3.5" /> 深度思考
  </Toggle>
</>

禁用

disabled 锁定按钮，按下态也可禁用。

tsx

<Toggle disabled defaultPressed aria-label="加粗"><Bold className="size-4" /></Toggle>

Props

Toggle

名称	类型	默认	说明
pressed	`boolean`	—	受控按下态
defaultPressed	`boolean`	`false`	非受控初始按下态
disabled	`boolean`	`false`	禁用
value	`string`	—	在 ToggleGroup 内标识该项
variant	`"default"｜"outline"｜"pill"`	`"default"`	default=灰底软选中 / outline=主色实心 / pill=圆角描边 + soft 主色选中（AI 工具栏开关风）
size	`"sm"｜"md"`	`"md"`	—
className	`string`	—	—
aria-label	`string`	—	仅图标时必填

ToggleGroup

名称	类型	默认	说明
value	`string[]`	—	受控：已按下项 value 数组
defaultValue	`string[]`	—	非受控初始按下项数组
disabled	`boolean`	`false`	整组禁用
multiple	`boolean`	`false`	true=多选共存；false=单选互斥
orientation	`"horizontal"｜"vertical"`	`"horizontal"`	—
className	`string`	—	—

事件

类型

说明

onPressedChange

(pressed: boolean) => void

按下态变化（瑚琏收敛签名，丢 Base UI eventDetails）

事件

类型

说明

onValueChange

(value: string[]) => void

变化回调

插槽

类型

说明

children

ReactNode

图标 / 文字

插槽

类型

说明

children

ReactNode

内放 Toggle 项

禁忌 / 坑

即便在 ToggleGroup 内，选中态也以 value 数组管理——multiple={false} 时数组里只会有 0 或 1 个元素。

仅渲染图标（无文字）的 Toggle 必须给 aria-label，否则读屏无名。

用 pressed/onPressedChange（或 group 的 value/onValueChange）即受控，须自管 state；非受控只给 defaultPressed/defaultValue。

Toggle

用法

基础用法

单选组

多选组

变体

禁用

何时用

导入

Props

Events

Slots

禁忌 / 坑

相关

Playground

Toggle

用法

基础用法

单选组

多选组

变体

禁用

何时用

导入

Props

Events

Slots

禁忌 / 坑

相关

Playground