Radio Button
A radio button component for single-selection within a group, with support for vertical and horizontal layouts.
RadioGroup Vertical (Default)
RadioGroup Horizontal
With Helper Text
Choose how often you'd like to receive notifications
With Error
Please select a delivery method
Disabled Group
Payment methods are currently unavailable
Pre-selected Option
Individual Disabled Radio
RadioGroup Props
| Name | Type | Default | Description |
|---|---|---|---|
label* | string | - | Radio group label text |
value | string | - | Controlled selected value |
defaultValue | string | - | Uncontrolled default selected value |
disabled | boolean | false | Whether entire group is disabled |
error | string | - | Error message to display |
helperText | string | - | Helper text below group |
orientation | 'vertical' | 'horizontal' | 'vertical' | Layout direction |
onChange | (value: string) => void | - | Change event handler |
children* | ReactNode | - | RadioButton components |
RadioButton Props
| Name | Type | Default | Description |
|---|---|---|---|
label* | string | - | Radio button label text |
value* | string | - | Value when selected |
checked | boolean | - | Whether radio is checked (controlled by RadioGroup) |
disabled | boolean | false | Whether individual radio is disabled |
onChange | (e: ChangeEvent) => void | - | Change event handler (managed by RadioGroup) |
Usage Guidelines
When to use
- •When users need to select exactly one option from a list of 2-7 choices
- •When all available options should be visible at once
- •For mutually exclusive settings or preferences
- •When selection needs to be immediately visible to users
Best practices
- •Use vertical layout by default for better readability
- •Use horizontal layout only when space is limited and options are short
- •Provide clear, concise labels for each option
- •Use helper text to provide additional context about the choices
- •Consider pre-selecting the most common or recommended option
- •For more than 7 options, consider using a Select component instead
- •Always provide a group label that describes what users are choosing
Accessibility
- •Keyboard accessible: Tab for focus, Arrow keys to navigate within group, Space to select
- •ARIA attributes: role="radiogroup", aria-checked, aria-invalid, aria-describedby
- •Error messages announced with aria-live
- •Focus indicators visible with 2px ring
- •Labels properly associated with radio inputs
- •Group label uses fieldset/legend for semantic grouping
- •Disabled state indicated with aria-disabled
- •Arrow key navigation follows roving tabindex pattern
Do's and Don'ts
✓ Do
- •Use radio buttons when there are 2-7 mutually exclusive options
- •Display all options at once so users can compare choices
- •Use vertical layout for better readability and scanning
- •Provide clear labels that describe each option
- •Pre-select the most common or recommended option
✗ Don't
- •Don't use radio buttons for multiple selections (use checkboxes)
- •Don't use for more than 7 options (use Select instead)
- •Don't use horizontal layout for long option labels
- •Don't nest radio groups or mix with other input types in same group
- •Don't use radio buttons for binary yes/no choices (use Switch or Toggle)
Related Components
Checkbox
For multiple selections from a list
Select
For choosing one option from many choices
Switch
For binary on/off or true/false choices