0
# Radix UI React Dialog
1

2
Radix UI React Dialog is a high-quality, accessible dialog component system for React applications. It provides modal overlays, popups, and dialog windows with proper accessibility features, focus management, keyboard navigation, and screen reader support as part of the Radix UI primitives collection.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import {
15
  Dialog,
16
  DialogTrigger,
17
  DialogContent,
18
  DialogTitle,
19
  DialogDescription,
20
  DialogClose,
21
  DialogOverlay,
22
  DialogPortal
23
} from "@radix-ui/react-dialog";
24
```
25

26
Alternative import pattern with short names:
27

28
```typescript
29
import {
30
  Root,
31
  Trigger,
32
  Content,
33
  Title,
34
  Description,
35
  Close,
36
  Overlay,
37
  Portal
38
} from "@radix-ui/react-dialog";
39
```
40

41
For CommonJS:
42

43
```javascript
44
const {
45
  Dialog,
46
  DialogTrigger,
47
  DialogContent,
48
  DialogTitle,
49
  DialogDescription,
50
  DialogClose
51
} = require("@radix-ui/react-dialog");
52
```
53

54
## Basic Usage
55

56
```typescript
57
import {
58
  Dialog,
59
  DialogTrigger,
60
  DialogContent,
61
  DialogTitle,
62
  DialogDescription,
63
  DialogClose,
64
  DialogOverlay,
65
  DialogPortal
66
} from "@radix-ui/react-dialog";
67

68
function MyDialog() {
69
  return (
70
    <Dialog>
71
      <DialogTrigger asChild>
72
        <button>Open Dialog</button>
73
      </DialogTrigger>
74
      <DialogPortal>
75
        <DialogOverlay className="dialog-overlay" />
76
        <DialogContent className="dialog-content">
77
          <DialogTitle>Are you sure?</DialogTitle>
78
          <DialogDescription>
79
            This action cannot be undone. This will permanently delete your account.
80
          </DialogDescription>
81
          <div className="dialog-actions">
82
            <DialogClose asChild>
83
              <button>Cancel</button>
84
            </DialogClose>
85
            <DialogClose asChild>
86
              <button className="destructive">Yes, delete account</button>
87
            </DialogClose>
88
          </div>
89
        </DialogContent>
90
      </DialogPortal>
91
    </Dialog>
92
  );
93
}
94
```
95

96
## Architecture
97

98
Radix UI React Dialog is built around a compound component pattern with several key components:
99

100
- **Root Component**: `Dialog` provides context and state management for the entire dialog system
101
- **Trigger System**: `DialogTrigger` handles opening the dialog with proper accessibility attributes
102
- **Portal Rendering**: `DialogPortal` renders content outside the normal DOM flow for proper layering
103
- **Overlay Management**: `DialogOverlay` provides modal background with scroll locking
104
- **Content Container**: `DialogContent` manages focus trapping, keyboard navigation, and dismissal
105
- **Accessibility Components**: `DialogTitle` and `DialogDescription` provide proper ARIA labeling
106
- **Close Controls**: `DialogClose` enables multiple ways to close the dialog
107
- **Context Scoping**: Advanced context management for nested or multiple dialog instances
108

109
## Capabilities
110

111
### Root Dialog Component
112

113
Core dialog root component that provides context and state management for all child components.
114

115
```typescript { .api }
116
interface DialogProps {
117
  children?: React.ReactNode;
118
  open?: boolean;
119
  defaultOpen?: boolean;
120
  onOpenChange?(open: boolean): void;
121
  modal?: boolean;
122
}
123

124
const Dialog: React.FC<DialogProps>;
125
```
126

127
[Dialog Root Component](./dialog-root.md)
128

129
### Dialog Triggers and Controls
130

131
Components for opening and closing dialogs with proper accessibility and focus management.
132

133
```typescript { .api }
134
interface DialogTriggerProps extends React.ComponentPropsWithoutRef<typeof Primitive.button> {}
135
interface DialogCloseProps extends React.ComponentPropsWithoutRef<typeof Primitive.button> {}
136

137
const DialogTrigger: React.ForwardRefExoticComponent<DialogTriggerProps>;
138
const DialogClose: React.ForwardRefExoticComponent<DialogCloseProps>;
139
```
140

141
[Triggers and Controls](./triggers-controls.md)
142

143
### Portal and Layout
144

145
Portal rendering and overlay components for proper dialog layering and modal behavior.
146

147
```typescript { .api }
148
interface DialogPortalProps {
149
  children?: React.ReactNode;
150
  container?: PortalProps['container'];
151
  forceMount?: true;
152
}
153

154
interface DialogOverlayProps extends React.ComponentPropsWithoutRef<typeof Primitive.div> {
155
  forceMount?: true;
156
}
157

158
const DialogPortal: React.FC<DialogPortalProps>;
159
const DialogOverlay: React.ForwardRefExoticComponent<DialogOverlayProps>;
160
```
161

162
[Portal and Layout](./portal-layout.md)
163

164
### Content and Accessibility
165

166
Main content container with focus management and accessibility components.
167

168
```typescript { .api }
169
interface DialogContentProps extends DialogContentTypeProps {
170
  forceMount?: true;
171
}
172

173
interface DialogTitleProps extends React.ComponentPropsWithoutRef<typeof Primitive.h2> {}
174
interface DialogDescriptionProps extends React.ComponentPropsWithoutRef<typeof Primitive.p> {}
175

176
const DialogContent: React.ForwardRefExoticComponent<DialogContentProps>;
177
const DialogTitle: React.ForwardRefExoticComponent<DialogTitleProps>;
178
const DialogDescription: React.ForwardRefExoticComponent<DialogDescriptionProps>;
179
```
180

181
[Content and Accessibility](./content-accessibility.md)
182

183
### Advanced Context Management
184

185
Utilities for advanced use cases like nested dialogs and custom context scoping.
186

187
```typescript { .api }
188
const createDialogScope: () => {
189
  Provider: React.Provider<any>;
190
  useScope: () => any;
191
};
192

193
const WarningProvider: React.Provider<any>;
194
```
195

196
[Advanced Context Management](./advanced-context.md)
197

198
## Alternative Export Names
199

200
All components are also available with shorter names for convenience:
201

202
```typescript { .api }
203
const Root: typeof Dialog;
204
const Trigger: typeof DialogTrigger;
205
const Portal: typeof DialogPortal;
206
const Overlay: typeof DialogOverlay;
207
const Content: typeof DialogContent;
208
const Title: typeof DialogTitle;
209
const Description: typeof DialogDescription;
210
const Close: typeof DialogClose;
211
```
212

213
## Element Types
214

215
Reference types for component elements:
216

217
```typescript { .api }
218
type DialogTriggerElement = React.ComponentRef<typeof Primitive.button>;
219
type DialogPortalElement = never; // Portal doesn't render a DOM element
220
type DialogOverlayElement = React.ComponentRef<typeof Primitive.div>;
221
type DialogContentElement = React.ComponentRef<typeof Primitive.div>;
222
type DialogTitleElement = React.ComponentRef<typeof Primitive.h2>;
223
type DialogDescriptionElement = React.ComponentRef<typeof Primitive.p>;
224
type DialogCloseElement = React.ComponentRef<typeof Primitive.button>;
225
```
226

227
## Key Features
228

229
- **Full Accessibility**: ARIA attributes, focus management, screen reader support
230
- **Keyboard Navigation**: ESC to close, Tab navigation, Enter/Space activation
231
- **Focus Management**: Focus trapping, auto-focus on open/close, focus restoration
232
- **Modal and Non-modal**: Supports both blocking overlays and non-blocking dialogs
233
- **Portal Rendering**: Content rendered outside normal DOM flow
234
- **Customizable**: All components accept standard HTML props for styling
235
- **Animation Support**: `forceMount` props for controlling mount/unmount timing
236
- **TypeScript**: Full type safety with comprehensive type definitions
237
- **Controlled/Uncontrolled**: Supports both usage patterns
238
- **Compound Components**: Composable API for maximum flexibility