0
# Dialog Root Component
1

2
The root Dialog component provides context and state management for the entire dialog system. It manages the open/closed state, coordinates between trigger and content components, and provides accessibility context.
3

4
## Capabilities
5

6
### Dialog Root
7

8
Root component that establishes dialog context and manages state for all child components.
9

10
```typescript { .api }
11
/**
12
 * Root dialog component that provides context and state management
13
 * @param props - Dialog configuration and children
14
 * @returns Dialog context provider with state management
15
 */
16
interface DialogProps {
17
  /** Child components that make up the dialog */
18
  children?: React.ReactNode;
19
  /** Controlled open state of the dialog */
20
  open?: boolean;
21
  /** Default open state for uncontrolled usage */
22
  defaultOpen?: boolean;
23
  /** Callback fired when the open state changes */
24
  onOpenChange?(open: boolean): void;
25
  /** Whether the dialog should be modal (default: true) */
26
  modal?: boolean;
27
}
28

29
const Dialog: React.FC<DialogProps>;
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import { Dialog, DialogTrigger, DialogContent } from "@radix-ui/react-dialog";
36

37
// Basic uncontrolled dialog
38
function BasicDialog() {
39
  return (
40
    <Dialog>
41
      <DialogTrigger>Open</DialogTrigger>
42
      <DialogContent>
43
        Dialog content here
44
      </DialogContent>
45
    </Dialog>
46
  );
47
}
48

49
// Controlled dialog with state
50
function ControlledDialog() {
51
  const [open, setOpen] = React.useState(false);
52
  
53
  return (
54
    <Dialog open={open} onOpenChange={setOpen}>
55
      <DialogTrigger>Open</DialogTrigger>
56
      <DialogContent>
57
        <p>This dialog is controlled by external state</p>
58
        <button onClick={() => setOpen(false)}>Close</button>
59
      </DialogContent>
60
    </Dialog>
61
  );
62
}
63

64
// Non-modal dialog
65
function NonModalDialog() {
66
  return (
67
    <Dialog modal={false}>
68
      <DialogTrigger>Open Non-Modal</DialogTrigger>
69
      <DialogContent>
70
        This dialog doesn't block interaction with background content
71
      </DialogContent>
72
    </Dialog>
73
  );
74
}
75

76
// Dialog with default open state
77
function DefaultOpenDialog() {
78
  return (
79
    <Dialog defaultOpen>
80
      <DialogTrigger>Already Open</DialogTrigger>
81
      <DialogContent>
82
        This dialog starts open by default
83
      </DialogContent>
84
    </Dialog>
85
  );
86
}
87
```
88

89
### State Management
90

91
The Dialog component provides both controlled and uncontrolled state patterns:
92

93
#### Controlled Usage
94

95
When both `open` and `onOpenChange` are provided, the dialog operates in controlled mode where you manage the state externally:
96

97
```typescript
98
const [isOpen, setIsOpen] = React.useState(false);
99

100
<Dialog open={isOpen} onOpenChange={setIsOpen}>
101
  {/* Dialog components */}
102
</Dialog>
103
```
104

105
#### Uncontrolled Usage
106

107
When neither `open` nor `onOpenChange` are provided, the dialog manages its own internal state:
108

109
```typescript
110
<Dialog>
111
  {/* Dialog components */}
112
</Dialog>
113
```
114

115
#### Default Open State
116

117
You can set an initial open state for uncontrolled dialogs:
118

119
```typescript
120
<Dialog defaultOpen={true}>
121
  {/* Dialog starts open */}
122
</Dialog>
123
```
124

125
### Modal vs Non-Modal
126

127
The `modal` prop controls whether the dialog blocks interaction with background content:
128

129
#### Modal Dialog (Default)
130

131
```typescript
132
<Dialog modal={true}> {/* or just <Dialog> */}
133
  {/* Background is blocked, focus is trapped */}
134
</Dialog>
135
```
136

137
Modal dialogs provide:
138
- Background content is blocked from interaction
139
- Focus is trapped within the dialog
140
- Overlay is rendered by default
141
- Scroll is locked on the body
142
- ESC key closes the dialog
143
- Click outside closes the dialog
144

145
#### Non-Modal Dialog
146

147
```typescript
148
<Dialog modal={false}>
149
  {/* Background remains interactive */}
150
</Dialog>
151
```
152

153
Non-modal dialogs provide:
154
- Background content remains interactive
155
- Focus can move outside the dialog
156
- No overlay is rendered by default
157
- No scroll locking
158
- More flexible interaction patterns
159

160
## Context and Internal Architecture
161

162
The Dialog component establishes several internal contexts:
163

164
- **Dialog Context**: Provides state and refs to all child components
165
- **Portal Context**: Manages force mounting for animations
166
- **Warning Context**: Development-time accessibility warnings
167

168
These contexts are automatically consumed by child components like DialogTrigger, DialogContent, etc.