Choicebox
choiceboxSelects one rich option from cards containing titles, descriptions, and supporting content.
Usage
Basic radio selection
Card-based single selection, for uncontrolled use defaultValue; each item can have an icon/title/description/additional content.
tsx
<ChoiceboxGroup defaultValue="pro" aria-label="Subscription Package" className="w-80">
<Choicebox value="free" icon={<Zap />} title="Basic version" description="Personal project · Free forever">
<div className="mt-1 font-semibold">¥0</div>
</Choicebox>
<Choicebox value="pro" icon={<Rocket />} title="Professional Edition" description="Small Team · Includes All Components">
<div className="mt-1 font-semibold">¥39/month</div>
</Choicebox>
</ChoiceboxGroup>Multiple selection + disabled items
multiple switches to multi-select semantics; single-item disabled locks the card.
tsx
<ChoiceboxGroup multiple defaultValue={["card"]} columns={1} aria-label="Payment method" className="w-72">
<Choicebox value="card" icon={<CreditCard />} title="Bank Card" description="Debit Card/Credit Card" />
<Choicebox value="wallet" icon={<Wallet />} title="Electronic Wallet" description="WeChat/Alipay" />
<Choicebox value="cash" icon={<Banknote />} title="Cash on delivery" disabled description="This region is not supported yet" />
</ChoiceboxGroup>Two column grid
columns Controls the number of grid columns, suitable for compact options without icons.
tsx
<ChoiceboxGroup defaultValue="b" columns={2} aria-label="Theme" className="w-[28rem]">
<Choicebox value="a" title="Light color" description="Bright interface" />
<Choicebox value="b" title="Dark" description="Dark interface" />
<Choicebox value="c" title="Follow the system" description="Automatic switching" />
<Choicebox value="d" title="High contrast" description="Barrier-free" />
</ChoiceboxGroup>When to use
Use Choicebox when each option needs a card with a title, description, and icon, such as a subscription plan, payment method, or theme level. Use ordinary Radio or Checkbox for a single line of text, or ColorSwatchPicker for color swatches.
Import
ts
import { ChoiceboxGroup, Choicebox } from "@hulianui/ui"Props
ChoiceboxGroup
| Name | Type | Default | Description |
|---|---|---|---|
| value | string | string[] | — | Controlled value: string for single selection and string[] for multiple selection. |
| defaultValue | string | string[] | — | Initial value when uncontrolled. |
| multiple | boolean | false | Enables checkbox-style multiple selection; otherwise the group uses radio semantics. |
| name | string | Automatically generated | Radio-group name in single-select mode. |
| columns | number | 1 | Number of grid columns |
| disabled | boolean | false | Disables the entire group. |
| className | string | — | Additional class name for the container. |
| aria-label | string | — | Accessible label. |
Choicebox
| Name | Type | Default | Description |
|---|---|---|---|
| value* | string | — | Option value, unique within the group. |
| disabled | boolean | false | Disables this option. |
| className | string | — | Additional class name for the card. |
Events
ChoiceboxGroup
| Event | Type | Description |
|---|---|---|
| onValueChange | (value: string | string[]) => void | Called with a string in single-select mode or string[] in multiple-select mode. |
Slots
ChoiceboxGroup
| Slot | Type | Description |
|---|---|---|
| children | ReactNode | A set of Choicebox options. |
Choicebox
| Slot | Type | Description |
|---|---|---|
| title | ReactNode | Primary title. |
| description | ReactNode | Supporting description. |
| icon | ReactNode | Leading icon. |
| children | ReactNode | Additional content beyond the title/description (price, tags, etc.) |
Usage guidelines
- Keep the
valueanddefaultValuetype aligned withmultiple: usestringfor single selection andstring[]for multiple selection. Mixing them produces inconsistent selection state. - Interactive controls inside Choicebox
children, such as delete or action buttons, conflict with the card-wide selection target. Stop event propagation from the nested control, or position it outside the radio/checkbox hit area.
Related
SecretField · Combobox · Listbox · Mentions · InputOTP · Rating
Playground
<ChoiceboxGroup defaultValue="a">
<Choicebox value="a" title="Option A" description="..." />
<Choicebox value="b" title="Option B" description="..." />
</ChoiceboxGroup>