组件 · 输入
RadioGroup
A group of round options for choosing one of 2 to 5 answers that is submitted with a form, each with room for a sentence.
也叫 Radio
import { RadioGroup } from "@botiverse/raft-ui";A radio group offers 2 to 5 answers that exclude each other, each with a line that explains it: who gets notified, who can mention @everyone. The chosen answer has an ink dot. Radios and switches are the only round controls in the system.
When to use
| Situation | Use |
|---|---|
| One of 2 to 5 answers, each worth a sentence | RadioGroup |
| Another view of the same content, switched in place | SegmentedControl |
| One of many values, or values people search | Select |
| A yes or no that applies at once | Switch |
| A yes or no saved with a form | Checkbox |
Anatomy
RadioGroup: the group. Holds the value. Required.RadioGroupItem: one answer's 20px circle with a 1.5px ink border, holding a hidden native input. Required, one per answer.RadioGroupIndicator: the 8px ink dot inside the chosen circle.RadioGroupItemrenders it by default.- A label: wrap each item, its label and its description in a
<label>, a flex row withitems-startandgap-2that carries the label's type. The circle centers on the label's first line by itself, 8px before it, at any min-height; don't add amargin-top(Alignment).
Variants
| Variant | Use for |
|---|---|
appearance="default" | A list of answers, each with a circle |
appearance="none" | An option card that shows the choice itself: the circle is visually hidden and the card draws the selected state |
States
- Chosen: an ink dot, not a yellow fill. A chosen value is ink, as a checked checkbox is, so radios and checkboxes agree and yellow stays for "you are here" (States).
- Disabled: the shared disabled look, for the circle and the label.
Behavior
- Make each answer a row at least 44px high, and make the whole row clickable. In its row the circle's hit area reaches 4px past its line, half the 8px gap between answers, so a tap between two lands on the nearer; the label is the target for the rest.
- Always have one answer chosen. Choose the most common and safest answer by default.
Content
- Set each answer's label in
text-subheadat weight 600, and its description intext-footnoteandforeground-muted.
Accessibility
RadioGroup wraps Base UI RadioGroup, and RadioGroupItem wraps Base UI Radio. The group is one tab stop; the arrow keys move between answers and choose them. Each item's hidden native input drives its checked, disabled and focus state, and the focus ring is drawn on the circle (States).
- Name the group:
aria-label, oraria-labelledbypointing at the visible question (Notify me about). - Name each answer with the
<label>around it.
API
RadioGroup
| Prop | 类型 | 默认值 |
|---|---|---|
| The uncontrolled value of the radio button that should be initially selected. | T | |
| Whether the component should ignore user interaction. | boolean | false |
| Identifies the form that owns the radio inputs. Useful when the radio group is rendered outside the form. | string | |
| A ref to access the hidden input element. | ((instance: HTMLInputElement | null) => void | (() => void | { [UNDEFINED_VOID_ONLY]: never; }) | DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES[keyof DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES]) | RefObject<HTMLInputElement | null> | |
| Identifies the field when a form is submitted. | string | |
| Callback fired when the value changes. | (value: T, eventDetails: BaseRadioGroup.ChangeEventDetails) => void | |
| Whether the user should be unable to select a different radio button in the group. | boolean | false |
| Allows you to replace the component's HTML element with a different tag, or compose it with another component. | ReactElement | ((props, state) => ReactElement) | |
| Whether the user must choose a value before submitting a form. | boolean | false |
| The controlled value of the radio item that should be currently selected. | T |
Also takes the attributes of its element.
RadioGroupIndicator
| Prop | 类型 | 默认值 |
|---|---|---|
| Whether to keep the HTML element in the DOM when the radio button is inactive. | boolean | false |
| Allows you to replace the component's HTML element with a different tag, or compose it with another component. | ReactElement | ((props, state) => ReactElement) |
Also takes the attributes of its element.
RadioGroupItem
| Prop | 类型 | 默认值 |
|---|---|---|
| "none" | "default" | "default" | |
| Whether the component should ignore user interaction. | boolean | |
| A ref to access the hidden input element. | ((instance: HTMLInputElement | null) => void | (() => void | { [UNDEFINED_VOID_ONLY]: never; }) | DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES[keyof DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES]) | RefObject<HTMLInputElement | null> | |
| Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. | boolean | false |
| Whether the user should be unable to select the radio button. | boolean | |
| Allows you to replace the component's HTML element with a different tag, or compose it with another component. | ReactElement | ((props, state) => ReactElement) | |
| Whether the user must choose a value before submitting a form. | boolean | |
| The unique identifying value of the radio in a group. | T |
Also takes the attributes of its element.