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