ToggleGroup

ToggleGroup 用于把多个 Toggle 组织成一组，支持单选和多选两种模式。组件基于 Radix Toggle Group 封装，并提供 items 数据驱动渲染、统一尺寸、视觉变体和 item 自定义渲染能力。

import { ToggleGroup, ToggleGroupItem, ToggleGroupRoot } from '@skyroc/web-ui';

何时使用

需要在一组选项中选择一个或多个状态，如文本对齐、编辑器格式、视图模式。
每个选项都可以用短文本、图标或自定义内容表达。
需要单选互斥时使用 type="single"；需要多项同时开启时使用 type="multiple"。
如果选项代表表单字段且需要明确的表单语义，可优先考虑 Radio 或 Checkbox。

单选

通过 type="single" 启用单选模式。defaultValue 和 value 使用单个字符串值。

Preview

Code

<ToggleGroup
  type="single"
  defaultValue="center"
  items={[
    { label: 'Left', value: 'left' },
    { label: 'Center', value: 'center' },
    { label: 'Right', value: 'right' }
  ]}
/>

多选

通过 type="multiple" 启用多选模式。defaultValue 和 value 使用字符串数组。

Preview

Code

<ToggleGroup
  type="multiple"
  defaultValue={['bold', 'underline']}
  items={[
    { label: 'Bold', value: 'bold' },
    { label: 'Italic', value: 'italic' },
    { label: 'Underline', value: 'underline' }
  ]}
/>

变体

通过 variant 设置整组 item 的视觉样式。当前实现支持 ghost 和 outline，单个 item 也可以在 items 中传入自己的 variant 覆盖组级设置。

Preview

Code

<ToggleGroup type="single" variant="outline" items={items} />

尺寸

通过 size 调整组间距以及每个 item 的高度、字号和横向内边距。默认尺寸为 md。

尺寸	Item 高度	字号	适用场景
`xs`	24px	10px	紧凑工具栏
`sm`	28px	12px	表格内操作、辅助项
`md`	32px	14px	常规场景（默认）
`lg`	36px	16px	强调操作
`xl`	40px	18px	大号操作区
`2xl`	48px	20px	大尺寸展示

Preview

Code

禁用项

可以在 item 数据上设置 disabled 禁用单个选项，也可以在根组件上设置 disabled 禁用整组。

Preview

Code

<ToggleGroup
  type="multiple"
  items={[
    { label: 'Top', value: 'top' },
    { disabled: true, label: 'Right', value: 'right' }
  ]}
/>

自定义渲染

通过 itemRender 自定义每个 item 的内容。classNames.groupRoot 控制根节点，classNames.toggle 会合并到每个 item。

Preview

Code

<ToggleGroup
  type="multiple"
  items={items}
  classNames={{ groupRoot: 'justify-start', toggle: 'gap-2' }}
  itemRender={item => (
    <>
      <span>{item.label}</span>
      <kbd>{item.shortcut}</kbd>
    </>
  )}
/>

API

ToggleGroup

数据驱动的切换组组件。继承 Radix Toggle Group Root 属性，并增加 items、itemRender、variant 和 slot class 配置。

属性	说明	类型	默认值
items*	切换项数据列表，每一项至少需要 value 和 label	ToggleGroupItemData[]	-
type*	选择模式	'single' \| 'multiple'	-
value	受控选中值；single 为字符串，multiple 为字符串数组	string \| string[]	-
defaultValue	非受控模式下的默认选中值	string \| string[]	-
onValueChange	选中值变化时触发	(value: string \| string[]) => void	-
variant	组内 item 的默认视觉样式	'ghost' \| 'outline'	'ghost'
size	尺寸，影响组间距和 item 样式	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	'md'
itemRender	自定义 item 内容渲染函数；未提供时使用 item.label	(item) => ReactNode	-
className	根节点自定义 class	ClassValue	-
classNames	各 slot 的自定义 class（groupRoot / toggle）	ToggleGroupClassNames	-
disabled	是否禁用整组	boolean	false
orientation	键盘导航方向	'horizontal' \| 'vertical'	-
dir	文本方向	'ltr' \| 'rtl'	-
loop	键盘导航是否循环	boolean	-
rovingFocus	是否启用 roving focus 键盘焦点管理	boolean	-

ToggleGroupRoot

底层根组件，继承 Radix Toggle Group Root 属性，不提供 items 数据渲染。

属性	说明	类型	默认值
type*	选择模式	'single' \| 'multiple'	-
value	受控选中值	string \| string[]	-
defaultValue	非受控默认选中值	string \| string[]	-
onValueChange	选中值变化回调	(value: string \| string[]) => void	-
className	根节点自定义 class	ClassValue	-
size	尺寸，影响组间距	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	'md'

ToggleGroupItem

底层 item 组件，继承 Radix Toggle Group Item 属性。

属性	说明	类型	默认值
value*	选项唯一值	string	-
disabled	是否禁用当前选项	boolean	false
variant	当前 item 的视觉样式；会覆盖组级 variant	'ghost' \| 'outline'	-
size	当前 item 的尺寸；会覆盖组级 size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	'md'
children	选项内容	ReactNode	-
className	当前 item 自定义 class	ClassValue	-

类型

ToggleGroupProps

ToggleGroup 主组件属性。继承 ToggleGroupRootProps，并增加数据驱动渲染、item 默认变体和 slot class 配置。

字段	类型	说明
className	ClassValue	根节点自定义 class。
classNames	ToggleGroupClassNames	各 slot 的自定义 class。
defaultValue	string \| string[]	非受控默认选中值。
disabled	boolean	是否禁用整组。
items	ToggleGroupItemData[]	切换项数据列表。
itemRender	(item) => ReactNode	自定义 item 内容渲染函数。
onValueChange	(value: string \| string[]) => void	选中值变化回调。
orientation	'horizontal' \| 'vertical'	键盘导航方向。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	组件尺寸。
type	'single' \| 'multiple'	选择模式。
value	string \| string[]	受控选中值。
variant	'ghost' \| 'outline'	组内 item 的默认视觉样式。

ToggleGroupItemData

ToggleGroup 的数据项类型。继承 ToggleGroupItemProps，但用 label 描述默认展示内容。

字段	类型	说明
label	ReactNode	默认展示内容。
value	string	选项唯一值。
disabled	boolean	是否禁用当前选项。
className	ClassValue	当前 item 自定义 class。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	当前 item 尺寸。
variant	'ghost' \| 'outline'	当前 item 视觉样式。
...itemProps	toggle group item props without children	其他 Radix ToggleGroup Item 属性。

ToggleGroupClassNames

各 slot 的自定义 class，用于精细化控制 ToggleGroup 样式。

字段	类型	说明
groupRoot	ClassValue	根节点的 class。
toggle	ClassValue	每个 item 的 class。

ToggleGroupRootProps

底层根组件属性。继承 Radix ToggleGroup Root 属性并支持项目尺寸。

字段	类型	说明
className	ClassValue	根节点自定义 class。
defaultValue	string \| string[]	非受控默认选中值。
disabled	boolean	是否禁用整组。
onValueChange	(value: string \| string[]) => void	选中值变化回调。
orientation	'horizontal' \| 'vertical'	键盘导航方向。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	组件尺寸。
type	'single' \| 'multiple'	选择模式。
value	string \| string[]	受控选中值。

ToggleGroupItemProps

底层 item 组件属性。继承 Radix ToggleGroup Item 属性并支持项目尺寸和 Toggle 变体。

字段	类型	说明
children	ReactNode	选项内容。
className	ClassValue	当前 item 自定义 class。
disabled	boolean	是否禁用当前选项。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	组件尺寸。
value	string	选项唯一值。
variant	'ghost' \| 'outline'	视觉样式。

StyledComponentProps<T>

项目内用于包装组件 props 的通用类型。

字段	类型	说明
...sourceProps	inherited props without className	继承原始组件属性，但重新定义 className。
className	ClassValue	组件 class。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	项目统一尺寸类型。

ClassValue

CSS 类名类型

string | null | undefined | Record<string, boolean> | ClassValue[]

ToggleGroup

ToggleGroupProps

ToggleGroupItemData

ToggleGroupClassNames

ToggleGroupRootProps

ToggleGroupItemProps

StyledComponentProps<T>

ClassValue

On this page