0
# Radix UI React Toggle Group
1

2
Radix UI React Toggle Group is an accessible React component library that provides toggle button groups supporting both single and multiple selection modes. It offers full keyboard navigation, customizable orientations, and maintains proper ARIA attributes while remaining completely unstyled for maximum design flexibility.
3

4
## Package Information
5

6
- **Package Name**: @radix-ui/react-toggle-group
7
- **Package Type**: npm
8
- **Version**: 1.1.11
9
- **Language**: TypeScript
10
- **License**: MIT
11
- **Homepage**: https://radix-ui.com/primitives
12
- **Installation**: `npm install @radix-ui/react-toggle-group`
13

14
## Core Imports
15

16
```typescript
17
import * as ToggleGroup from "@radix-ui/react-toggle-group";
18
```
19

20
Or with named imports:
21

22
```typescript
23
import { 
24
  ToggleGroup,
25
  ToggleGroupItem,
26
  Root, 
27
  Item, 
28
  ToggleGroupSingleProps, 
29
  ToggleGroupMultipleProps,
30
  ToggleGroupItemProps,
31
  createToggleGroupScope
32
} from "@radix-ui/react-toggle-group";
33
```
34

35
Required peer dependencies:
36

37
```typescript
38
import React from "react";
39
```
40

41
For type definitions (if using TypeScript):
42

43
```typescript
44
import type { Scope } from "@radix-ui/react-context";
45
import type { Primitive } from "@radix-ui/react-primitive";
46
import type * as RovingFocusGroup from "@radix-ui/react-roving-focus";
47
import type { Toggle } from "@radix-ui/react-toggle";
48
```
49

50
For CommonJS:
51

52
```javascript
53
const ToggleGroup = require("@radix-ui/react-toggle-group");
54
```
55

56
## Basic Usage
57

58
```typescript
59
import React from "react";
60
import * as ToggleGroup from "@radix-ui/react-toggle-group";
61

62
// Single selection mode
63
function SingleToggleGroup() {
64
  const [value, setValue] = React.useState("");
65
  
66
  return (
67
    <ToggleGroup.Root
68
      type="single"
69
      value={value}
70
      onValueChange={setValue}
71
    >
72
      <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
73
      <ToggleGroup.Item value="center">Center</ToggleGroup.Item>
74
      <ToggleGroup.Item value="right">Right</ToggleGroup.Item>
75
    </ToggleGroup.Root>
76
  );
77
}
78

79
// Multiple selection mode
80
function MultipleToggleGroup() {
81
  const [value, setValue] = React.useState<string[]>([]);
82
  
83
  return (
84
    <ToggleGroup.Root
85
      type="multiple"
86
      value={value} 
87
      onValueChange={setValue}
88
    >
89
      <ToggleGroup.Item value="bold">Bold</ToggleGroup.Item>
90
      <ToggleGroup.Item value="italic">Italic</ToggleGroup.Item>
91
      <ToggleGroup.Item value="underline">Underline</ToggleGroup.Item>
92
    </ToggleGroup.Root>
93
  );
94
}
95
```
96

97
## Advanced Usage
98

99
### Using Default Values
100

101
```typescript
102
// Single selection with default value
103
function DefaultSingleToggle() {
104
  return (
105
    <ToggleGroup.Root
106
      type="single"
107
      defaultValue="center"
108
    >
109
      <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
110
      <ToggleGroup.Item value="center">Center</ToggleGroup.Item>
111
      <ToggleGroup.Item value="right">Right</ToggleGroup.Item>
112
    </ToggleGroup.Root>
113
  );
114
}
115

116
// Multiple selection with default values
117
function DefaultMultipleToggle() {
118
  return (
119
    <ToggleGroup.Root
120
      type="multiple"
121
      defaultValue={["bold", "italic"]}
122
    >
123
      <ToggleGroup.Item value="bold">Bold</ToggleGroup.Item>
124
      <ToggleGroup.Item value="italic">Italic</ToggleGroup.Item>
125
      <ToggleGroup.Item value="underline">Underline</ToggleGroup.Item>
126
    </ToggleGroup.Root>
127
  );
128
}
129
```
130

131
### Disabled and Configuration Options
132

133
```typescript
134
function ConfiguredToggleGroup() {
135
  return (
136
    <ToggleGroup.Root
137
      type="single"
138
      disabled={true}
139
      orientation="vertical"
140
      dir="rtl"
141
      loop={false}
142
      rovingFocus={false}
143
    >
144
      <ToggleGroup.Item value="option1">Option 1</ToggleGroup.Item>
145
      <ToggleGroup.Item value="option2">Option 2</ToggleGroup.Item>
146
      <ToggleGroup.Item value="option3" disabled={false}>Option 3 (enabled)</ToggleGroup.Item>
147
    </ToggleGroup.Root>
148
  );
149
}
150
```
151

152
### Horizontal vs Vertical Orientation
153

154
```typescript
155
// Horizontal toggle group (default)
156
function HorizontalToggle() {
157
  return (
158
    <ToggleGroup.Root type="single" orientation="horizontal">
159
      <ToggleGroup.Item value="prev">Previous</ToggleGroup.Item>
160
      <ToggleGroup.Item value="next">Next</ToggleGroup.Item>
161
    </ToggleGroup.Root>
162
  );
163
}
164

165
// Vertical toggle group
166
function VerticalToggle() {
167
  return (
168
    <ToggleGroup.Root type="single" orientation="vertical">
169
      <ToggleGroup.Item value="top">Top</ToggleGroup.Item>
170
      <ToggleGroup.Item value="middle">Middle</ToggleGroup.Item>
171
      <ToggleGroup.Item value="bottom">Bottom</ToggleGroup.Item>
172
    </ToggleGroup.Root>
173
  );
174
}
175
```
176

177
## Architecture
178

179
The component is built on Radix UI's primitive system with several key integrations:
180

181
- **Context Management**: Uses `@radix-ui/react-context` for internal state sharing
182
- **Roving Focus**: Integrates `@radix-ui/react-roving-focus` for keyboard navigation
183
- **Toggle Primitives**: Built on `@radix-ui/react-toggle` for individual item behavior
184
- **Controllable State**: Uses `@radix-ui/react-use-controllable-state` for controlled/uncontrolled patterns
185
- **Directional Support**: Integrates `@radix-ui/react-direction` for RTL/LTR layouts
186

187
## Accessibility
188

189
Radix UI React Toggle Group follows the WAI-ARIA guidelines and provides comprehensive accessibility features:
190

191
### ARIA Attributes
192

193
**Toggle Group Container:**
194
- Automatically sets `role="group"` on the root container
195
- Properly manages `dir` attribute for RTL/LTR support
196

197
**Single Selection Mode:**
198
- Individual items use `role="radio"` for radio button semantics
199
- Sets `aria-checked` to indicate selection state
200
- Removes default `aria-pressed` attribute to avoid conflicts
201

202
**Multiple Selection Mode:**
203
- Individual items use default toggle button semantics with `aria-pressed`
204
- Multiple items can be selected simultaneously
205

206
### Keyboard Navigation
207

208
**Roving Focus (enabled by default):**
209
- Arrow keys navigate between toggle items
210
- `Tab` enters/exits the group
211
- Focus management respects `orientation` (horizontal/vertical)
212
- `loop` prop controls whether focus wraps around
213

214
**Focus Management:**
215
- `disabled` items are excluded from focus sequence
216
- Focus is properly maintained when items are added/removed
217
- Supports custom focus behavior via `rovingFocus={false}`
218

219
### Error Handling
220

221
The component includes built-in error handling:
222
- Throws clear error when required `type` prop is missing
223
- Gracefully handles undefined/null values in controlled mode
224
- Maintains consistent state even with invalid configurations
225

226
## Capabilities
227

228
### Toggle Group Root Component
229

230
Main container component that manages the selection state and provides context to child items.
231

232
```typescript { .api }
233
const ToggleGroup: React.ForwardRefExoticComponent<
234
  (ToggleGroupSingleProps | ToggleGroupMultipleProps) & React.RefAttributes<ToggleGroupElement>
235
>;
236

237
const Root: typeof ToggleGroup;
238
```
239

240
### Toggle Group Item Component
241

242
Individual toggle button that can be pressed/unpressed within the group.
243

244
```typescript { .api }
245
const ToggleGroupItem: React.ForwardRefExoticComponent<
246
  ToggleGroupItemProps & React.RefAttributes<ToggleGroupItemElement>
247
>;
248

249
const Item: typeof ToggleGroupItem;
250
```
251

252
### Context Scope Creation
253

254
Utility function for creating scoped contexts when composing with other Radix components.
255

256
```typescript { .api }
257
const createToggleGroupScope: () => Scope;
258
```
259

260
## Types
261

262
### Single Selection Props
263

264
Props interface for toggle groups that allow only one selected item at a time.
265

266
```typescript { .api }
267
interface ToggleGroupImplSingleProps extends ToggleGroupImplProps {
268
  /** The controlled stateful value of the item that is pressed */
269
  value?: string;
270
  /** The value of the item that is pressed when initially rendered */
271
  defaultValue?: string;
272
  /** The callback that fires when the value of the toggle group changes */
273
  onValueChange?(value: string): void;
274
}
275

276
interface ToggleGroupSingleProps extends ToggleGroupImplSingleProps {
277
  /** Selection mode - must be 'single' */
278
  type: 'single';
279
}
280
```
281

282
### Multiple Selection Props
283

284
Props interface for toggle groups that allow multiple selected items simultaneously.
285

286
```typescript { .api }
287
interface ToggleGroupImplMultipleProps extends ToggleGroupImplProps {
288
  /** The controlled stateful value of the items that are pressed */
289
  value?: string[];
290
  /** The value of the items that are pressed when initially rendered */
291
  defaultValue?: string[];
292
  /** The callback that fires when the state of the toggle group changes */
293
  onValueChange?(value: string[]): void;
294
}
295

296
interface ToggleGroupMultipleProps extends ToggleGroupImplMultipleProps {
297
  /** Selection mode - must be 'multiple' */
298
  type: 'multiple';
299
}
300
```
301

302
### Common Implementation Props
303

304
Base props shared between single and multiple selection modes.
305

306
```typescript { .api }
307
type RovingFocusGroupProps = React.ComponentPropsWithoutRef<typeof RovingFocusGroup.Root>;
308
type PrimitiveDivProps = React.ComponentPropsWithoutRef<typeof Primitive.div>;
309

310
interface ToggleGroupImplProps extends PrimitiveDivProps {
311
  /** Whether the group is disabled from user interaction. @defaultValue false */
312
  disabled?: boolean;
313
  /** Whether the group should maintain roving focus of its buttons. @defaultValue true */
314
  rovingFocus?: boolean;
315
  /** Whether focus should loop from last to first item. @defaultValue true */
316
  loop?: RovingFocusGroupProps['loop'];
317
  /** The orientation of the toggle group */
318
  orientation?: RovingFocusGroupProps['orientation'];
319
  /** The reading direction of the toggle group */
320
  dir?: RovingFocusGroupProps['dir'];
321
}
322
```
323

324
### Toggle Group Item Props
325

326
Props interface for individual toggle items within the group.
327

328
```typescript { .api }
329
type ToggleProps = React.ComponentPropsWithoutRef<typeof Toggle>;
330

331
interface ToggleGroupItemImplProps extends Omit<ToggleProps, 'defaultPressed' | 'onPressedChange'> {
332
  /** A string value for the toggle group item. All items within a toggle group should use a unique value */
333
  value: string;
334
}
335

336
interface ToggleGroupItemProps extends Omit<ToggleGroupItemImplProps, 'pressed'> {}
337
```
338

339
### Element Type Aliases
340

341
Type definitions for component element references.
342

343
```typescript { .api }
344
type ToggleGroupImplElement = React.ComponentRef<typeof Primitive.div>;
345
type ToggleGroupElement = ToggleGroupImplSingleElement | ToggleGroupImplMultipleElement;
346
type ToggleGroupImplSingleElement = ToggleGroupImplElement;
347
type ToggleGroupImplMultipleElement = ToggleGroupImplElement;
348

349
type ToggleGroupItemImplElement = React.ComponentRef<typeof Toggle>;
350
type ToggleGroupItemElement = ToggleGroupItemImplElement;
351
```
352

353
### Context Utilities
354

355
Context-related types for advanced composition patterns with other Radix components.
356

357
```typescript { .api }
358
type Scope = Record<string, React.Context<any>>;
359
```