0
# Radix UI Alert Dialog
1

2
Radix UI Alert Dialog provides low-level, accessible React components for building alert dialogs. Alert dialogs are modal dialogs that demand user attention and action before continuing, with enhanced accessibility features including proper focus management, keyboard navigation, and screen reader support.
3

4
## Package Information
5

6
- **Package Name**: @radix-ui/react-alert-dialog
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @radix-ui/react-alert-dialog`
10

11
## Core Imports
12

13
```typescript
14
import * as AlertDialog from "@radix-ui/react-alert-dialog";
15
```
16

17
Or import specific components:
18

19
```typescript
20
import {
21
  AlertDialog,
22
  AlertDialogTrigger,
23
  AlertDialogPortal,
24
  AlertDialogOverlay,
25
  AlertDialogContent,
26
  AlertDialogTitle,
27
  AlertDialogDescription,
28
  AlertDialogAction,
29
  AlertDialogCancel,
30
} from "@radix-ui/react-alert-dialog";
31
```
32

33
For CommonJS:
34

35
```javascript
36
const AlertDialog = require("@radix-ui/react-alert-dialog");
37
```
38

39
## Basic Usage
40

41
```typescript
42
import * as AlertDialog from "@radix-ui/react-alert-dialog";
43

44
function MyAlertDialog() {
45
  return (
46
    <AlertDialog.Root>
47
      <AlertDialog.Trigger asChild>
48
        <button>Delete item</button>
49
      </AlertDialog.Trigger>
50
      <AlertDialog.Portal>
51
        <AlertDialog.Overlay />
52
        <AlertDialog.Content>
53
          <AlertDialog.Title>Are you absolutely sure?</AlertDialog.Title>
54
          <AlertDialog.Description>
55
            This action cannot be undone. This will permanently delete your item.
56
          </AlertDialog.Description>
57
          <div style={{ display: "flex", gap: 25, justifyContent: "flex-end" }}>
58
            <AlertDialog.Cancel asChild>
59
              <button>Cancel</button>
60
            </AlertDialog.Cancel>
61
            <AlertDialog.Action asChild>
62
              <button>Yes, delete item</button>
63
            </AlertDialog.Action>
64
          </div>
65
        </AlertDialog.Content>
66
      </AlertDialog.Portal>
67
    </AlertDialog.Root>
68
  );
69
}
70
```
71

72
## Architecture
73

74
Alert Dialog follows a compound component pattern where each part serves a specific role:
75

76
- **Root**: Manages dialog state and provides context to child components
77
- **Trigger**: Opens the dialog when activated
78
- **Portal**: Renders dialog content in a separate DOM location (typically document.body)
79
- **Overlay**: Background layer behind the dialog content
80
- **Content**: Main dialog container with accessibility features
81
- **Title & Description**: Accessible labeling required for screen readers
82
- **Action & Cancel**: Interactive buttons that close the dialog
83

84
Key differences from regular dialogs:
85
- Always modal (cannot be dismissed by clicking outside)
86
- Prevents escape key dismissal
87
- Auto-focuses the cancel button when opened
88
- Requires explicit user action to dismiss
89

90
## Capabilities
91

92
### Root Component
93

94
The root container that manages dialog state and provides context to all child components.
95

96
```typescript { .api }
97
interface AlertDialogProps {
98
  children?: React.ReactNode;
99
  open?: boolean;
100
  defaultOpen?: boolean;
101
  onOpenChange?: (open: boolean) => void;
102
}
103

104
const AlertDialog: React.FC<AlertDialogProps>;
105
```
106

107
Also available as:
108

109
```typescript { .api }
110
const Root: React.FC<AlertDialogProps>;
111
```
112

113
### Trigger Component
114

115
Button or element that opens the alert dialog when activated.
116

117
```typescript { .api }
118
interface AlertDialogTriggerProps extends React.ComponentPropsWithoutRef<'button'> {
119
  asChild?: boolean;
120
}
121

122
const AlertDialogTrigger: React.ForwardRefExoticComponent<
123
  AlertDialogTriggerProps & React.RefAttributes<HTMLButtonElement>
124
>;
125
```
126

127
Also available as:
128

129
```typescript { .api }
130
const Trigger: React.ForwardRefExoticComponent<
131
  AlertDialogTriggerProps & React.RefAttributes<HTMLButtonElement>
132
>;
133
```
134

135
### Portal Component
136

137
Renders dialog content outside the normal DOM tree, typically in document.body.
138

139
```typescript { .api }
140
interface AlertDialogPortalProps {
141
  children?: React.ReactNode;
142
  container?: HTMLElement;
143
  forceMount?: true;
144
}
145

146
const AlertDialogPortal: React.FC<AlertDialogPortalProps>;
147
```
148

149
Also available as:
150

151
```typescript { .api }
152
const Portal: React.FC<AlertDialogPortalProps>;
153
```
154

155
### Overlay Component
156

157
Background layer that appears behind the dialog content.
158

159
```typescript { .api }
160
interface AlertDialogOverlayProps extends React.ComponentPropsWithoutRef<'div'> {
161
  asChild?: boolean;
162
  forceMount?: true;
163
}
164

165
const AlertDialogOverlay: React.ForwardRefExoticComponent<
166
  AlertDialogOverlayProps & React.RefAttributes<HTMLDivElement>
167
>;
168
```
169

170
Also available as:
171

172
```typescript { .api }
173
const Overlay: React.ForwardRefExoticComponent<
174
  AlertDialogOverlayProps & React.RefAttributes<HTMLDivElement>
175
>;
176
```
177

178
### Content Component
179

180
Main dialog container with built-in accessibility features and focus management.
181

182
```typescript { .api }
183
interface AlertDialogContentProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'onPointerDownOutside' | 'onInteractOutside'> {
184
  asChild?: boolean;
185
  forceMount?: true;
186
  onEscapeKeyDown?: (event: KeyboardEvent) => void;
187
  onOpenAutoFocus?: (event: Event) => void;
188
  onCloseAutoFocus?: (event: Event) => void;
189
}
190

191
const AlertDialogContent: React.ForwardRefExoticComponent<
192
  AlertDialogContentProps & React.RefAttributes<HTMLDivElement>
193
>;
194
```
195

196
Also available as:
197

198
```typescript { .api }
199
const Content: React.ForwardRefExoticComponent<
200
  AlertDialogContentProps & React.RefAttributes<HTMLDivElement>
201
>;
202
```
203

204
**Key behaviors:**
205
- Sets `role="alertdialog"` for accessibility
206
- Prevents pointer and interaction events outside the dialog (`onPointerDownOutside` and `onInteractOutside` are internally prevented)
207
- Automatically focuses the cancel button when opened
208
- Prevents dismissal via escape key or outside clicks
209

210
### Title Component
211

212
Required accessible title for the alert dialog.
213

214
```typescript { .api }
215
interface AlertDialogTitleProps extends React.ComponentPropsWithoutRef<'h2'> {
216
  asChild?: boolean;
217
}
218

219
const AlertDialogTitle: React.ForwardRefExoticComponent<
220
  AlertDialogTitleProps & React.RefAttributes<HTMLHeadingElement>
221
>;
222
```
223

224
Also available as:
225

226
```typescript { .api }
227
const Title: React.ForwardRefExoticComponent<
228
  AlertDialogTitleProps & React.RefAttributes<HTMLHeadingElement>
229
>;
230
```
231

232
### Description Component
233

234
Required accessible description for the alert dialog content.
235

236
```typescript { .api }
237
interface AlertDialogDescriptionProps extends React.ComponentPropsWithoutRef<'p'> {
238
  asChild?: boolean;
239
}
240

241
const AlertDialogDescription: React.ForwardRefExoticComponent<
242
  AlertDialogDescriptionProps & React.RefAttributes<HTMLParagraphElement>
243
>;
244
```
245

246
Also available as:
247

248
```typescript { .api }
249
const Description: React.ForwardRefExoticComponent<
250
  AlertDialogDescriptionProps & React.RefAttributes<HTMLParagraphElement>
251
>;
252
```
253

254
**Note**: The Description component is required for accessibility. In development mode, a console warning will be logged if the description is missing or not properly linked via `aria-describedby`. The warning provides detailed guidance on how to add proper descriptions for screen readers.
255

256
### Action Component
257

258
Primary action button that closes the dialog and executes the main action.
259

260
```typescript { .api }
261
interface AlertDialogActionProps extends React.ComponentPropsWithoutRef<'button'> {
262
  asChild?: boolean;
263
}
264

265
const AlertDialogAction: React.ForwardRefExoticComponent<
266
  AlertDialogActionProps & React.RefAttributes<HTMLButtonElement>
267
>;
268
```
269

270
Also available as:
271

272
```typescript { .api }
273
const Action: React.ForwardRefExoticComponent<
274
  AlertDialogActionProps & React.RefAttributes<HTMLButtonElement>
275
>;
276
```
277

278
### Cancel Component
279

280
Cancel button that closes the dialog without executing the main action. Receives focus when the dialog opens.
281

282
```typescript { .api }
283
interface AlertDialogCancelProps extends React.ComponentPropsWithoutRef<'button'> {
284
  asChild?: boolean;
285
}
286

287
const AlertDialogCancel: React.ForwardRefExoticComponent<
288
  AlertDialogCancelProps & React.RefAttributes<HTMLButtonElement>
289
>;
290
```
291

292
Also available as:
293

294
```typescript { .api }
295
const Cancel: React.ForwardRefExoticComponent<
296
  AlertDialogCancelProps & React.RefAttributes<HTMLButtonElement>
297
>;
298
```
299

300
**Key behavior**: Automatically receives focus when the alert dialog opens.
301

302
### Utility Functions
303

304
Advanced composition utility for creating scoped alert dialog contexts.
305

306
```typescript { .api }
307
/**
308
 * Creates a scoped context for alert dialog components
309
 * Used for advanced composition scenarios with multiple dialog instances
310
 */
311
function createAlertDialogScope(): CreateScope;
312

313
interface CreateScope {
314
  scopeName: string;
315
  (): ScopeHook;
316
}
317

318
type ScopeHook = (scope: Scope) => { [__scopeProp: string]: Scope };
319
type Scope<C = any> = { [scopeName: string]: React.Context<C>[] } | undefined;
320
```
321

322
## Common Props
323

324
### asChild Prop
325

326
Many components support the `asChild` prop for composition:
327

328
```typescript
329
// Default behavior - renders a button
330
<AlertDialog.Trigger>Open</AlertDialog.Trigger>
331

332
// With asChild - merges props with the child element
333
<AlertDialog.Trigger asChild>
334
  <MyCustomButton>Open</MyCustomButton>
335
</AlertDialog.Trigger>
336
```
337

338
### forceMount Prop
339

340
Content and Overlay components support `forceMount` for animation libraries:
341

342
```typescript
343
<AlertDialog.Overlay forceMount={shouldForceMount} />
344
<AlertDialog.Content forceMount={shouldForceMount}>
345
  {/* content */}
346
</AlertDialog.Content>
347
```
348

349
## Event Handling
350

351
```typescript
352
<AlertDialog.Root onOpenChange={(open) => console.log("Dialog is", open ? "open" : "closed")}>
353
  <AlertDialog.Content
354
    onOpenAutoFocus={(event) => {
355
      // Prevent default focus behavior if needed
356
      event.preventDefault();
357
    }}
358
    onCloseAutoFocus={(event) => {
359
      // Handle focus return when dialog closes
360
    }}
361
    onEscapeKeyDown={(event) => {
362
      // Escape key is prevented by default in alert dialogs
363
      // This handler won't typically fire unless custom behavior is needed
364
    }}
365
  >
366
    {/* content */}
367
  </AlertDialog.Content>
368
</AlertDialog.Root>
369
```
370

371
## Accessibility Features
372

373
- **ARIA Compliance**: Proper `role="alertdialog"` and ARIA labeling
374
- **Focus Management**: Automatic focus on cancel button, proper focus return
375
- **Keyboard Navigation**: Tab cycling within dialog, escape prevention
376
- **Screen Reader Support**: Required title and description announcement
377
- **Non-dismissible**: Cannot be closed by clicking outside or pressing escape
378
- **Development Warnings**: Console warnings in development mode for missing required accessibility components (specifically the Description component)