Radio

Radio 用于在多个互斥选项中选择一个值。组件基于 Radix Radio Group 封装，提供数据驱动的 RadioGroup、单个 Radio、结构组件，以及带图标和描述的 RadioCardGroup。

import {
  Radio,
  RadioCard,
  RadioCardGroup,
  RadioGroup,
  RadioGroupItem,
  RadioIndicator,
  RadioRoot
} from '@skyroc/web-ui';

何时使用

需要用户从一组选项中选择一个值。
选项数量较少，用户需要直接看到所有选项。
需要通过颜色、尺寸或卡片样式强调选项差异。
可以多选时使用 Checkbox；需要从大量选项中选择时使用 Select 或 Combobox。

基础用法

通过 items 渲染一组单选项。使用 defaultValue 设置默认选中项，使用 value 和 onValueChange 实现受控模式。

Preview

Code

<RadioGroup
  defaultValue="apple"
  items={[
    { label: 'Apple', value: 'apple' },
    { label: 'Orange', value: 'orange' }
  ]}
/>

颜色

通过 color 设置单选控件和指示器的主题色。颜色会应用到整组 Radio，也可在单个 item 上覆盖。

Preview

Code

颜色	语义	适用场景
`primary`	主要选项	常规表单、默认选择
`destructive`	危险选项	删除、不可逆配置
`success`	成功选项	正向状态、推荐方案
`warning`	警告选项	需要注意的配置
`info`	信息选项	中性信息类选择
`carbon`	中性深色	不带语义倾向的选项
`secondary`	次级选项	辅助配置、低优先级选择
`accent`	强调选项	需要特殊视觉关注的选择

变体

通过 variant 切换选中样式。dot 使用点状指示器，outline 会在选中后填充控件背景并反转指示器颜色。

Preview

Code

<RadioGroup
  defaultValue="apple"
  items={items}
  variant="outline"
/>

方向

通过 orientation 控制排列方向。默认横向排列，纵向排列适合表单字段和设置面板。

Preview

Code

<RadioGroup
  items={items}
  orientation="vertical"
/>

尺寸

通过 size 调整控件尺寸、组间距和标签间距，从 xs 到 2xl 共 6 个尺寸。

Preview

Code

尺寸	控件尺寸	适用场景
`xs`	12px	紧凑表单、表格内嵌
`sm`	14px	小型表单
`md`	16px	常规场景（默认）
`lg`	18px	强调选项
`xl`	20px	大号设置项
`2xl`	24px	大幅展示或卡片表单

禁用

可以禁用整个 RadioGroup，也可以只禁用某个 item。

Preview

Code

<RadioGroup
  items={[
    { label: 'A', value: 'a' },
    { disabled: true, label: 'B', value: 'b' }
  ]}
/>

Preview

Code

<RadioGroup disabled items={items} />

卡片组选项

RadioCardGroup 用卡片承载单选项，支持图标、标题、描述和单选控件位置，适合展示套餐、模板、支付方式等更复杂的选项。

Preview

Code

<RadioCardGroup
  defaultValue="apple"
  items={[
    { label: 'Apple', value: 'apple', description: 'This is an apple' },
    { label: 'Cherry', value: 'cherry', description: 'This is a cherry' }
  ]}
  radioPosition="right"
/>

API

RadioGroup

通用属性参考：基于 Radix RadioGroup Root，通过 items 数据渲染一组 Radio。

属性	说明	类型	默认值
items*	单选项数据	RadioProps[]	-
value	受控模式下当前选中的值	string	-
defaultValue	非受控模式下默认选中的值	string	-
onValueChange	选中值变化时触发	(value: string) => void	-
orientation	排列方向	'horizontal' \| 'vertical'	'horizontal'
color	主题颜色	'primary' \| 'destructive' \| 'success' \| 'warning' \| 'info' \| 'carbon' \| 'secondary' \| 'accent'	'primary'
variant	选中样式	'dot' \| 'outline'	'dot'
size	尺寸，影响控件大小、标签间距和组间距	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	'md'
disabled	是否禁用整组单选项	boolean	-
className	组容器 class	ClassValue	-
classNames	各 slot 的自定义 class	RadioClassNames	-

Radio

单个单选项。通常通过 RadioGroup.items 使用；手动组合时需要放在 Radix RadioGroup Root 下。

属性	说明	类型	默认值
value*	选项值	string	-
label	选项标签	ReactNode	-
disabled	是否禁用当前选项	boolean	-
color	当前选项主题色，会覆盖组级 color	'primary' \| 'destructive' \| 'success' \| 'warning' \| 'info' \| 'carbon' \| 'secondary' \| 'accent'	-
variant	当前选项选中样式	'dot' \| 'outline'	'dot'
size	当前选项尺寸	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	'md'
className	当前选项根容器 class	ClassValue	-
classNames	当前选项可覆盖的 slot class（root / control / indicator / label）	RadioClassNames	-
itemProps	传递给 RadioGroupItem 的额外 props	RadioGroupItemProps	-
indicatorProps	传递给 RadioIndicator 的额外 props	RadioIndicatorProps	-
rootProps	传递给 RadioRoot 的额外 props	RadioRootProps	-

RadioCardGroup

卡片式单选组。适合需要展示标题、描述和图标的场景。

属性	说明	类型	默认值
items*	卡片选项数据	RadioCardGroupItem[]	-
value	受控模式下当前选中的值	string	-
defaultValue	非受控模式下默认选中的值	string	-
onValueChange	选中值变化时触发	(value: string) => void	-
radioPosition	单选控件相对内容的位置	'left' \| 'right'	'right'
orientation	排列方向	'horizontal' \| 'vertical'	'horizontal'
color	主题颜色	'primary' \| 'destructive' \| 'success' \| 'warning' \| 'info' \| 'carbon' \| 'secondary' \| 'accent'	'primary'
variant	选中样式	'dot' \| 'outline'	'dot'
size	尺寸，影响卡片间距、文本和控件大小	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	'md'
disabled	是否禁用整组卡片选项	boolean	-
className	卡片组容器 class	ClassValue	-
classNames	各 slot 的自定义 class	RadioClassNames	-

结构组件

Radio 同时导出底层结构组件，适合需要手动组织 DOM 结构时使用。

属性	说明	类型	默认值
RadioRoot	单个 Radio 的外层容器	RadioRootProps	-
RadioGroupItem	Radix RadioGroup Item 包装	RadioGroupItemProps	-
RadioIndicator	选中指示器	RadioIndicatorProps	-
RadioCard	卡片式单选项	RadioCardProps	-

类型

RadioGroupProps

数据驱动单选组属性。继承 Radix RadioGroup Root props，并通过 items 渲染 Radio。

字段	类型	说明
items*	RadioProps[]	单选项数据。
value	string	受控选中值。
defaultValue	string	默认选中值。
onValueChange	(value: string) => void	选中值变化回调。
orientation	'horizontal' \| 'vertical'	排列方向。
color	'primary' \| 'destructive' \| 'success' \| 'warning' \| 'info' \| 'carbon' \| 'secondary' \| 'accent'	主题颜色。
variant	'dot' \| 'outline'	选中样式。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	组件尺寸。
disabled	boolean	是否禁用整组。
className	ClassValue	组容器 class。
classNames	RadioClassNames	slot class 配置。

RadioProps

单个 Radio 属性。继承 RadioGroupItemProps，并增加 label、rootProps、itemProps、indicatorProps 等封装字段。

字段	类型	说明
value*	string	选项值。
label	ReactNode	选项标签。
disabled	boolean	是否禁用当前选项。
color	'primary' \| 'destructive' \| 'success' \| 'warning' \| 'info' \| 'carbon' \| 'secondary' \| 'accent'	当前选项主题色。
variant	'dot' \| 'outline'	选中样式。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	组件尺寸。
className	ClassValue	根容器 class。
classNames	RadioClassNames	slot class 配置。
itemProps	RadioGroupItemProps	传递给内部 RadioGroupItem 的属性。
indicatorProps	RadioIndicatorProps	传递给内部 RadioIndicator 的属性。
rootProps	RadioRootProps	传递给内部 RadioRoot 的属性。

RadioCardGroupProps

卡片式单选组属性。继承 Radix RadioGroup Root props，并通过 items 渲染 RadioCard。

字段	类型	说明
items*	RadioCardGroupItem[]	卡片选项数据。
value	string	受控选中值。
defaultValue	string	默认选中值。
onValueChange	(value: string) => void	选中值变化回调。
radioPosition	'left' \| 'right'	单选控件位置。
orientation	'horizontal' \| 'vertical'	排列方向。
color	'primary' \| 'destructive' \| 'success' \| 'warning' \| 'info' \| 'carbon' \| 'secondary' \| 'accent'	主题颜色。
variant	'dot' \| 'outline'	选中样式。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	组件尺寸。
disabled	boolean	是否禁用整组。
className	ClassValue	组容器 class。
classNames	RadioClassNames	slot class 配置。

RadioCardGroupItem

卡片式单选组选项数据。

字段	类型	说明
value*	string	选项值。
label	ReactNode	卡片标题。
description	ReactNode	卡片描述。
icon	ReactNode	卡片图标。
disabled	boolean	是否禁用当前卡片。
itemProps	RadioGroupItemProps	传递给内部单选项的属性。
indicatorProps	RadioIndicatorProps	传递给内部指示器的属性。
rootProps	RadioRootProps	继承自 RadioProps 的字段，RadioCardGroup 当前不会直接使用。

RadioCardProps

单个卡片式 Radio 属性。

字段	类型	说明
value*	string	选项值。
checked	boolean	卡片外层选中状态。
label	ReactNode	卡片标题。
description	ReactNode	卡片描述。
icon	ReactNode	卡片图标。
radioPosition	'left' \| 'right'	单选控件位置。
disabled	boolean	是否禁用。
color	'primary' \| 'destructive' \| 'success' \| 'warning' \| 'info' \| 'carbon' \| 'secondary' \| 'accent'	主题颜色。
variant	'dot' \| 'outline'	选中样式。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	组件尺寸。
className	ClassValue	卡片 class。
classNames	RadioClassNames	slot class 配置。

RadioGroupItemProps

底层单选控件属性，继承 Radix RadioGroup Item props，并增加项目尺寸、颜色和变体。

字段	类型	说明
value*	string	选项值。
disabled	boolean	是否禁用。
color	'primary' \| 'destructive' \| 'success' \| 'warning' \| 'info' \| 'carbon' \| 'secondary' \| 'accent'	主题颜色。
variant	'dot' \| 'outline'	选中样式。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	组件尺寸。
className	ClassValue	控件 class。

RadioIndicatorProps

选中指示器属性，继承 Radix RadioGroup Indicator props，并增加项目颜色和变体。

字段	类型	说明
color	'primary' \| 'destructive' \| 'success' \| 'warning' \| 'info' \| 'carbon' \| 'secondary' \| 'accent'	主题颜色。
variant	'dot' \| 'outline'	选中样式。
className	ClassValue	指示器 class。

RadioRootProps

单个 Radio 外层容器属性，继承原生 div 属性，并增加项目尺寸。

字段	类型	说明
className	ClassValue	根容器 class。
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	组件尺寸。

RadioClassNames

Radio 各 slot 的自定义 class。

字段	类型	说明
group	ClassValue	组容器 class。
root	ClassValue	普通 Radio 外层容器 class。
control	ClassValue	单选控件 class。
indicator	ClassValue	选中指示器 class。
label	ClassValue	普通 Radio 标签 class。
card	ClassValue	卡片容器 class。
cardContent	ClassValue	卡片内容区域 class。
cardTextContent	ClassValue	卡片文本区域 class。
cardLabel	ClassValue	卡片标题 class。
cardDescription	ClassValue	卡片描述 class。

ClassValue

CSS 类名类型

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

Radio

RadioGroupProps

RadioProps

RadioCardGroupProps

RadioCardGroupItem

RadioCardProps

RadioGroupItemProps

RadioIndicatorProps

RadioRootProps

RadioClassNames

ClassValue

On this page