Formsstable
Radio Group
A set of checkable buttons—known as radio buttons—where no more than one can be checked at a time.
Installation
Install the component directly into your project using the Pittaya CLI.
npx pittaya@latest add radio-group
When to use
Use the Radio Group component when you need users to select exactly one option from a list of mutually exclusive choices. Unlike checkboxes, only one radio button can be selected at a time within a group.
Radio groups are ideal for settings, preferences, payment methods, shipping options, or any scenario where users must make a single selection from predefined options.
Best practices
- Always provide clear and concise labels for each radio option.
- Use radio groups when you have 2-5 options. For more options, consider using a select dropdown instead.
- Set a sensible default value with
defaultValueto guide users toward common choices. - Group related radio buttons together using a
<fieldset>and<legend>for better semantics and accessibility. - Use the Radix UI native
orientationprop to control keyboard navigation direction (doesn't affect visual layout). - Ensure labels are clickable by properly associating them with radio buttons using
idandhtmlForattributes.
Accessibility
The Radio Group component is built on top of Radix UI's radio group primitive, providing full keyboard navigation and screen reader support out of the box.
- Keyboard support: Use Tab to focus the group, arrow keys (↑ ↓ ← →) to navigate between options, and Space to select.
- Focus is clearly indicated with a ring outline for better visibility.
- The component properly communicates the selected state to assistive technologies using ARIA attributes.
- Always wrap radio groups in a
<fieldset>with a<legend>to provide context. - Use the
requiredprop to indicate mandatory fields in forms.
Layout customization
By default, the Radio Group arranges options vertically. You can customize the layout using className to arrange items horizontally or in any other layout pattern:
- Vertical (default): Use the default behavior or
className="flex flex-col gap-2" - Horizontal: Add
className="flex flex-row gap-4"for side-by-side options - Grid: Use
className="grid grid-cols-2 gap-4"for a grid layout
Examples
Combine variants and sizes to meet your needs.
Programming language
A simple example for selecting a preferred programming language.
Deploy environments
Horizontal layout ideal for selecting deployment environments.
Deployment options
Example with disabled option for features under development.
Subscription plans
Plan selection with detailed descriptions for each option.
Framework selection
Controlled radio group with React state showing selection in real-time.
Backup configuration
Form integration with fieldset for system configuration settings.
Properties
TSX interface that combines variants and default attributes.
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | — | The controlled value of the selected radio button. Use with onValueChange for controlled components. |
defaultValue | string | — | The default value of the selected radio button when initially rendered. Use for uncontrolled components. |
onValueChange | (value: string) => void | — | Event handler called when the selected radio button changes. |
disabled | boolean | false | When true, prevents the user from interacting with all radio buttons in the group. |
required | boolean | false | When true, indicates that the user must select an option before submitting the form. |
name | string | — | The name of the radio group. Submitted with its owning form as part of a name/value pair. |
orientation | 'horizontal' | 'vertical' | undefined | undefined | Controls keyboard navigation direction (not visual layout). Use className to control visual layout. |