Choicebox
choicebox卡片选择 · 复合 ChoiceboxGroup/Choicebox(标题/描述/图标卡片) · 单选(radio)/多选(checkbox)对称 + 受控非受控 + 网格列数 · 隐藏原生 input 承载键盘与 a11y(单选方向键漫游/多选空格切换) · 套餐/支付方式/订阅档位
用法
基础单选
卡片化单选，非受控用 defaultValue；每项可带图标/标题/描述/附加内容。
tsx
<ChoiceboxGroup defaultValue="pro" aria-label="订阅套餐" className="w-80">
<Choicebox value="free" icon={<Zap />} title="基础版" description="个人项目 · 永久免费">
<div className="mt-1 font-semibold">¥0</div>
</Choicebox>
<Choicebox value="pro" icon={<Rocket />} title="专业版" description="小团队 · 含全部组件">
<div className="mt-1 font-semibold">¥39 / 月</div>
</Choicebox>
</ChoiceboxGroup>多选 + 禁用项
multiple 切换为多选语义；单项 disabled 锁定该卡片。
tsx
<ChoiceboxGroup multiple defaultValue={["card"]} columns={1} aria-label="支付方式" className="w-72">
<Choicebox value="card" icon={<CreditCard />} title="银行卡" description="储蓄卡 / 信用卡" />
<Choicebox value="wallet" icon={<Wallet />} title="电子钱包" description="微信 / 支付宝" />
<Choicebox value="cash" icon={<Banknote />} title="货到付款" disabled description="该地区暂不支持" />
</ChoiceboxGroup>两列网格
columns 控制网格列数，适合无图标的紧凑选项。
tsx
<ChoiceboxGroup defaultValue="b" columns={2} aria-label="主题" className="w-[28rem]">
<Choicebox value="a" title="浅色" description="明亮界面" />
<Choicebox value="b" title="深色" description="暗黑界面" />
<Choicebox value="c" title="跟随系统" description="自动切换" />
<Choicebox value="d" title="高对比" description="无障碍" />
</ChoiceboxGroup>何时用
每个选项需要标题+描述+图标的卡片化呈现时用（订阅套餐、支付方式、主题档位）。若选项只是一行文字用普通 Radio/Checkbox；若是色块用 ColorSwatchPicker。
导入
ts
import { ChoiceboxGroup, Choicebox } from "@hulianui/ui"Props
ChoiceboxGroup
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | string | string[] | — | 受控值。单选为 string，多选为 string[] |
| defaultValue | string | string[] | — | 非受控初值 |
| multiple | boolean | false | true=多选(checkbox 语义) / false=单选(radio 语义) |
| name | string | 自动生成 | radio 分组 name（单选用） |
| columns | number | 1 | 网格列数 |
| disabled | boolean | false | 整组禁用 |
| className | string | — | 透传到容器 |
| aria-label | string | — | 无障碍标签 |
Choicebox
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value* | string | — | 选项值（组内唯一） |
| disabled | boolean | false | 单项禁用 |
| className | string | — | 透传到卡片 |
Events
ChoiceboxGroup
| 事件 | 类型 | 说明 |
|---|---|---|
| onValueChange | (value: string | string[]) => void | 变更回调；单选回传 string，多选回传 string[] |
Slots
ChoiceboxGroup
| 插槽 | 类型 | 说明 |
|---|---|---|
| children | ReactNode | 一组 Choicebox |
Choicebox
| 插槽 | 类型 | 说明 |
|---|---|---|
| title | ReactNode | 主标题 |
| description | ReactNode | 副描述 |
| icon | ReactNode | 左侧图标 |
| children | ReactNode | 标题/描述外的附加内容（价格、标签等） |
禁忌 / 坑
value/defaultValue类型随multiple：单选传string，多选传string[]，搞反会导致选中态错乱。- 在 Choicebox 的
children里放删除/操作钮等交互元素时，会与卡片整体的选中点击冲突，需对子元素阻断冒泡（或用绝对定位让它脱离单选环的点击区）。
相关
SecretField · Combobox · Listbox · Mentions · InputOTP · Rating
Playground
<ChoiceboxGroup defaultValue="a">
<Choicebox value="a" title="选项 A" description="…" />
<Choicebox value="b" title="选项 B" description="…" />
</ChoiceboxGroup>