Single-choice selection controls for mutually exclusive options. Users can select exactly one option from a set. Uses convex physics with the selected indicator animating in with a spring effect. Use radio buttons when only one selection is allowed.
Physics: Radio buttons use convex shadows for depth. On hover, the button elevates slightly (-1px). The inner dot scales in with spring easing when selected.
Use RadioGroup with options array for simple single-choice selection.
Add secondary text to help users understand each option.
Arrange radio buttons horizontally for compact layouts.
Disable specific options that are temporarily unavailable.
Mark the group as required with a visual indicator.
Display validation errors when no option is selected.
Confirm successful selection with a success status.
Compare all three sizes for different density requirements.
Disable the entire group when the section is not applicable.
Common pattern for payment method selection with descriptions.
Use individual Radio components for custom layouts.
Add group-level helper text for additional context.
| Prop | Type | Default | Description |
|---|---|---|---|
name | string | required | Form field name (required for radio groups) |
value | T | - | Controlled selected value |
defaultValue | T | - | Initial selected value (uncontrolled) |
onChange | (value: T) => void | - | Callback when selection changes |
options | RadioGroupOption[] | - | Array of options with value, label, description |
orientation | 'horizontal' | 'vertical' | 'vertical' | Layout direction |
size | 'sm' | 'md' | 'lg' | 'md' | Radio button size |
label | string | - | Group label |
helperText | string | - | Helper text below group |
status | 'default' | 'success' | 'error' | 'default' | Validation status |
required | boolean | false | Mark as required |
disabled | boolean | false | Disable entire group |
role="radiogroup" with aria-required