Radio Group
A set of checkable buttons where only one can be checked at a time.
Overview
The Radio Group component allows users to select a single option from a list of mutually exclusive choices. Radio groups are commonly used in forms, surveys, and settings where users need to make a single selection from multiple options.
Our Radio Group component is built with Radix UI primitives and follows WAI-ARIA best practices. It supports keyboard navigation, focus management, and screen reader announcements.
Basic Usage
The default Radio Group component provides a clean, accessible set of radio buttons.
Examples
With Form Label
Add a form label to provide context for the radio group.
Subscription Plan
Card Radio Group
Create a more visual radio group using cards.
Disabled State
Radio items can be disabled to prevent user interaction.
API Reference
The Radio Group component consists of two parts: RadioGroup (the container) and RadioGroupItem (the individual radio buttons).
| Component | Props | Description |
|---|---|---|
| RadioGroup | defaultValue?: string value?: string onValueChange?: (value: string) => void disabled?: boolean required?: boolean name?: string className?: string | The container component that manages the state of the radio group and provides context for the radio items. |
| RadioGroupItem | value: string disabled?: boolean required?: boolean className?: string | An individual radio button that can be selected. Each item must have a unique value within the group. |
All components accept standard HTML attributes in addition to the props listed above.
Usage Guidelines
Follow these guidelines for effective use of the Radio Group component:
When to Use
Do
- Use when users need to select exactly one option from a list
- Use when options are mutually exclusive
- Provide clear, concise labels for each option
- Group related radio buttons together
- Consider using a default selected value when appropriate
Don't
- Use when users need to select multiple options (use checkboxes instead)
- Use when there are too many options (consider a select component)
- Use without labels or with unclear labels
- Use for binary choices (consider a single checkbox or toggle)
- Place radio buttons too close together, making them difficult to select
Layout and Presentation
Do
- Arrange radio buttons vertically for better readability
- Use consistent spacing between options
- Consider visual enhancements like cards for important choices
- Provide adequate touch targets for mobile users
- Use descriptive text to explain the consequences of each choice
Don't
- Arrange radio buttons horizontally if there are more than 3-4 options
- Use inconsistent styling across different radio groups
- Hide or obscure the selected state
- Change the order of options dynamically
- Use radio buttons for actions (use buttons instead)
Accessibility
The Radio Group component is designed with accessibility in mind, following WAI-ARIA best practices.
Keyboard Navigation
Users can navigate between radio buttons using the arrow keys, and select an option using the Space key.
ARIA Attributes
The component uses appropriate ARIA roles and states to communicate the purpose and state of the radio buttons to assistive technologies.
Accessibility Tip
Always associate labels with radio buttons using the htmlFor attribute that matches the radio button's id. This ensures that users can click on the label to select the radio button, and screen readers can announce the label when the radio button is focused.