0
# Radix UI React Radio Group
1
2
A set of checkable buttons—known as radio buttons—where no more than one of the buttons can be checked at a time. This package provides a comprehensive and accessible RadioGroup component for React applications with full keyboard navigation support, ARIA compliance, and flexible orientation options.
3
4
## Package Information
5
6
- **Package Name**: @radix-ui/react-radio-group
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @radix-ui/react-radio-group`
10
11
## Core Imports
12
13
```typescript
14
import { RadioGroup, RadioGroupItem, RadioGroupIndicator } from "@radix-ui/react-radio-group";
15
```
16
17
Alternative import with aliases:
18
19
```typescript
20
import { Root, Item, Indicator } from "@radix-ui/react-radio-group";
21
```
22
23
For CommonJS:
24
25
```javascript
26
const { RadioGroup, RadioGroupItem, RadioGroupIndicator } = require("@radix-ui/react-radio-group");
27
```
28
29
## Basic Usage
30
31
```typescript
32
import { useState } from "react";
33
import { RadioGroup, RadioGroupItem, RadioGroupIndicator } from "@radix-ui/react-radio-group";
34
35
function PaymentForm() {
36
const [paymentMethod, setPaymentMethod] = useState("card");
37
38
return (
39
<RadioGroup value={paymentMethod} onValueChange={setPaymentMethod}>
40
<div style={{ display: "flex", alignItems: "center" }}>
41
<RadioGroupItem value="card" id="card">
42
<RadioGroupIndicator />
43
</RadioGroupItem>
44
<label htmlFor="card">Credit Card</label>
45
</div>
46
47
<div style={{ display: "flex", alignItems: "center" }}>
48
<RadioGroupItem value="paypal" id="paypal">
49
<RadioGroupIndicator />
50
</RadioGroupItem>
51
<label htmlFor="paypal">PayPal</label>
52
</div>
53
54
<div style={{ display: "flex", alignItems: "center" }}>
55
<RadioGroupItem value="bank" id="bank">
56
<RadioGroupIndicator />
57
</RadioGroupItem>
58
<label htmlFor="bank">Bank Transfer</label>
59
</div>
60
</RadioGroup>
61
);
62
}
63
```
64
65
## Architecture
66
67
The RadioGroup component follows Radix UI's compound component pattern:
68
69
- **RadioGroup (Root)**: Container that manages state, focus, and keyboard navigation using roving focus
70
- **RadioGroupItem**: Individual selectable radio button with automatic ARIA attributes
71
- **RadioGroupIndicator**: Visual indicator that appears only when the parent item is selected
72
- **Context System**: Internal context providers handle state sharing between components
73
- **Focus Management**: Arrow key navigation with automatic focus management via roving focus
74
- **Form Integration**: Native HTML form behavior with hidden input elements for form submission
75
76
## Capabilities
77
78
### RadioGroup Root Component
79
80
The root container that manages radio group state, focus behavior, and keyboard navigation.
81
82
```typescript { .api }
83
interface RadioGroupProps extends React.ComponentPropsWithoutRef<"div"> {
84
/**
85
* The name of the radio group. Submitted with its owning form as part of a name/value pair.
86
*/
87
name?: string;
88
89
/**
90
* When true, indicates that the user must select a value before the owning form can be submitted.
91
*/
92
required?: boolean;
93
94
/**
95
* When true, prevents the user from interacting with radio items.
96
*/
97
disabled?: boolean;
98
99
/**
100
* The reading direction of the radio group. If omitted, inherits globally from DirectionProvider or assumes LTR (left-to-right) reading mode.
101
*/
102
dir?: "ltr" | "rtl";
103
104
/**
105
* The orientation of the component.
106
*/
107
orientation?: "horizontal" | "vertical";
108
109
/**
110
* When true, keyboard navigation will loop from last item to first, and vice versa.
111
* @defaultValue true
112
*/
113
loop?: boolean;
114
115
/**
116
* The value of the radio item that should be checked when initially rendered. Use when you do not need to control the state of the radio items.
117
*/
118
defaultValue?: string;
119
120
/**
121
* The controlled value of the radio item to check. Should be used in conjunction with onValueChange.
122
*/
123
value?: string | null;
124
125
/**
126
* Event handler called when the value changes.
127
*/
128
onValueChange?: (value: string) => void;
129
}
130
131
const RadioGroup: React.ForwardRefExoticComponent<
132
RadioGroupProps & React.RefAttributes<HTMLDivElement>
133
>;
134
```
135
136
### RadioGroupItem Component
137
138
Individual radio button component that integrates with the RadioGroup's state management.
139
140
```typescript { .api }
141
interface RadioGroupItemProps extends Omit<React.ComponentPropsWithoutRef<"button">, "onCheck" | "name"> {
142
/**
143
* The value given as data when submitted with a name.
144
*/
145
value: string;
146
}
147
148
const RadioGroupItem: React.ForwardRefExoticComponent<
149
RadioGroupItemProps & React.RefAttributes<HTMLButtonElement>
150
>;
151
```
152
153
### RadioGroupIndicator Component
154
155
Visual indicator component that renders only when its parent RadioGroupItem is in the checked state.
156
157
```typescript { .api }
158
interface RadioGroupIndicatorProps extends React.ComponentPropsWithoutRef<"span"> {
159
/**
160
* Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.
161
*/
162
forceMount?: true;
163
}
164
165
const RadioGroupIndicator: React.ForwardRefExoticComponent<
166
RadioGroupIndicatorProps & React.RefAttributes<HTMLSpanElement>
167
>;
168
```
169
170
### Scope Creation Utility
171
172
Advanced utility for creating isolated contexts when composing with other Radix primitives.
173
174
```typescript { .api }
175
/**
176
* Creates a scope for RadioGroup context isolation.
177
* Used for advanced composition scenarios with other Radix primitives.
178
* @returns Scope creation function for context isolation
179
*/
180
function createRadioGroupScope(): Scope;
181
```
182
183
### Component Aliases
184
185
Alternative exports with shorter names for convenience.
186
187
```typescript { .api }
188
/**
189
* Alias for RadioGroup component
190
*/
191
const Root: typeof RadioGroup;
192
193
/**
194
* Alias for RadioGroupItem component
195
*/
196
const Item: typeof RadioGroupItem;
197
198
/**
199
* Alias for RadioGroupIndicator component
200
*/
201
const Indicator: typeof RadioGroupIndicator;
202
```
203
204
### Form Integration Example
205
206
Proper form integration with name attribute and form submission:
207
208
```typescript
209
import { useState } from "react";
210
import { RadioGroup, RadioGroupItem, RadioGroupIndicator } from "@radix-ui/react-radio-group";
211
212
function FormExample() {
213
const [method, setMethod] = useState("card");
214
215
const handleSubmit = (event: React.FormEvent<HTMLFormElement>) => {
216
event.preventDefault();
217
const formData = new FormData(event.currentTarget);
218
console.log('Payment method:', formData.get('paymentMethod'));
219
};
220
221
return (
222
<form onSubmit={handleSubmit}>
223
<RadioGroup
224
name="paymentMethod"
225
value={method}
226
onValueChange={setMethod}
227
required
228
>
229
<div style={{ display: "flex", alignItems: "center" }}>
230
<RadioGroupItem value="card" id="card">
231
<RadioGroupIndicator />
232
</RadioGroupItem>
233
<label htmlFor="card">Credit Card</label>
234
</div>
235
236
<div style={{ display: "flex", alignItems: "center" }}>
237
<RadioGroupItem value="paypal" id="paypal">
238
<RadioGroupIndicator />
239
</RadioGroupItem>
240
<label htmlFor="paypal">PayPal</label>
241
</div>
242
</RadioGroup>
243
244
<button type="submit">Submit</button>
245
</form>
246
);
247
}
248
```
249
250
## Exported Types
251
252
All component prop types are exported for TypeScript usage:
253
254
```typescript { .api }
255
export type {
256
RadioGroupProps,
257
RadioGroupItemProps,
258
RadioGroupIndicatorProps
259
};
260
```
261
262
## Key Features
263
264
### Accessibility
265
- Full ARIA compliance with proper roles and attributes
266
- Screen reader support with descriptive announcements
267
- Keyboard navigation using arrow keys
268
- Focus management with visual focus indicators
269
270
### Keyboard Navigation
271
- **Arrow Keys**: Navigate between radio items
272
- **Tab**: Move focus into and out of the radio group
273
- **Space**: Select the focused radio item
274
- **Enter**: Prevented (following WAI-ARIA patterns)
275
276
### State Management
277
- **Controlled**: Use `value` and `onValueChange` props
278
- **Uncontrolled**: Use `defaultValue` prop
279
- Automatic state synchronization between items
280
281
### Form Integration
282
- Native HTML form behavior
283
- Hidden input elements for proper form submission (via internal RadioBubbleInput component)
284
- Support for `name` attribute and form validation
285
- Event bubbling and form change events
286
287
### Customization
288
- Flexible styling via CSS classes and data attributes
289
- Support for custom components via `asChild` pattern (internal)
290
- Animation support through `forceMount` on indicators
291
- Orientation and direction control