0
# Basic Modal Management
1

2
Core modal operations for opening, closing, and updating content modals with custom children.
3

4
## Capabilities
5

6
### Open Modal
7

8
Creates and displays a modal with custom content.
9

10
```typescript { .api }
11
/**
12
 * Opens a modal with custom content
13
 * @param props - Modal configuration and content
14
 * @returns Modal ID for future reference
15
 */
16
function openModal(props: ModalSettings): string;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { openModal } from "@mantine/modals";
23
import { Text, Button } from "@mantine/core";
24

25
// Simple text modal
26
const modalId = openModal({
27
  title: "Information",
28
  children: <Text>This is important information.</Text>,
29
});
30

31
// Modal with custom content
32
openModal({
33
  title: "User Details",
34
  size: "lg",
35
  children: (
36
    <div>
37
      <Text mb="md">User profile information:</Text>
38
      <Text>Name: John Doe</Text>
39
      <Text>Email: john@example.com</Text>
40
    </div>
41
  ),
42
  onClose: () => console.log("Modal closed"),
43
});
44

45
// Modal with specific ID
46
openModal({
47
  modalId: "welcome-modal",
48
  title: "Welcome!",
49
  centered: true,
50
  children: <Text>Welcome to our application!</Text>,
51
});
52
```
53

54
### Close Modal
55

56
Closes a specific modal by ID.
57

58
```typescript { .api }
59
/**
60
 * Closes a specific modal by ID
61
 * @param id - Modal ID to close
62
 */
63
function closeModal(id: string): void;
64
```
65

66
**Usage Examples:**
67

68
```typescript
69
import { openModal, closeModal } from "@mantine/modals";
70

71
// Open modal and store ID
72
const modalId = openModal({
73
  title: "Temporary Modal",
74
  children: <Text>This modal will close automatically</Text>,
75
});
76

77
// Close after 3 seconds
78
setTimeout(() => {
79
  closeModal(modalId);
80
}, 3000);
81

82
// Close specific modal by known ID
83
closeModal("welcome-modal");
84
```
85

86
### Close All Modals
87

88
Closes all currently open modals.
89

90
```typescript { .api }
91
/**
92
 * Closes all currently open modals
93
 */
94
function closeAllModals(): void;
95
```
96

97
**Usage Examples:**
98

99
```typescript
100
import { closeAllModals } from "@mantine/modals";
101

102
// Emergency close all modals
103
function handleEscapePress() {
104
  closeAllModals();
105
}
106

107
// Reset modal state
108
function resetApp() {
109
  closeAllModals();
110
  // ... other reset logic
111
}
112
```
113

114
### Update Modal
115

116
Updates properties of an existing modal.
117

118
```typescript { .api }
119
/**
120
 * Updates properties of an existing modal
121
 * @param payload - Modal ID and updated properties
122
 */
123
function updateModal(payload: { modalId: string } & Partial<ModalSettings>): void;
124
```
125

126
**Usage Examples:**
127

128
```typescript
129
import { openModal, updateModal } from "@mantine/modals";
130

131
// Open initial modal
132
const modalId = openModal({
133
  title: "Loading...",
134
  children: <Text>Please wait...</Text>,
135
});
136

137
// Update modal content after data loads
138
setTimeout(() => {
139
  updateModal({
140
    modalId,
141
    title: "Data Loaded",
142
    children: (
143
      <div>
144
        <Text>Data has been successfully loaded!</Text>
145
        <Text c="green">✓ Process completed</Text>
146
      </div>
147
    ),
148
  });
149
}, 2000);
150

151
// Update modal size
152
updateModal({
153
  modalId: "user-details",
154
  size: "xl",
155
  centered: false,
156
});
157
```
158

159
### Modals Namespace Object
160

161
Namespace object containing all modal management functions.
162

163
```typescript { .api }
164
/**
165
 * Namespace object with all modal management functions
166
 */
167
const modals: {
168
  open: (props: ModalSettings) => string;
169
  close: (id: string) => void;
170
  closeAll: () => void;
171
  openConfirmModal: (props: OpenConfirmModal) => string;
172
  openContextModal: <TKey extends MantineModal>(
173
    payload: OpenContextModal<Parameters<MantineModals[TKey]>[0]['innerProps']> & { modal: TKey }
174
  ) => string;
175
  updateModal: (payload: { modalId: string } & Partial<ModalSettings>) => void;
176
  updateContextModal: (payload: { modalId: string } & Partial<OpenContextModal<any>>) => void;
177
};
178
```
179

180
**Usage Examples:**
181

182
```typescript
183
import { modals } from "@mantine/modals";
184

185
// Use namespace object instead of individual functions
186
const modalId = modals.open({
187
  title: "Namespace Example",
188
  children: <Text>Using modals namespace</Text>,
189
});
190

191
// Close using namespace
192
modals.close(modalId);
193

194
// Close all using namespace
195
modals.closeAll();
196
```
197

198
## Modal Settings Interface
199

200
Complete modal configuration options.
201

202
> **Note**: `ModalProps` is from `@mantine/core` - see [Mantine Modal documentation](https://mantine.dev/core/modal/) for complete prop definitions.
203

204
```typescript { .api }
205
/**
206
 * Base modal configuration extending Mantine Modal props
207
 */
208
interface ModalSettings extends Partial<Omit<ModalProps, 'opened'>> {
209
  /** Unique identifier for the modal */
210
  modalId?: string;
211
  /** Modal content */
212
  children?: React.ReactNode;
213
  /** Modal title */
214
  title?: React.ReactNode;
215
  /** Callback when modal is closed */
216
  onClose?: () => void;
217
  /** Modal size: xs, sm, md, lg, xl, or number */
218
  size?: string | number;
219
  /** Whether modal is centered vertically */
220
  centered?: boolean;
221
  /** Whether modal can be closed by clicking overlay */
222
  closeOnClickOutside?: boolean;
223
  /** Whether modal can be closed by pressing Escape */
224
  closeOnEscape?: boolean;
225
  /** Modal content padding */
226
  padding?: string | number;
227
  /** Modal border radius */
228
  radius?: string | number;
229
  /** Modal shadow */
230
  shadow?: string;
231
  /** Modal z-index */
232
  zIndex?: number;
233
  /** Overlay properties */
234
  overlayProps?: {
235
    backgroundOpacity?: number;
236
    blur?: number;
237
    color?: string;
238
  };
239
  /** Transition properties */
240
  transitionProps?: {
241
    duration?: number;
242
    transition?: string;
243
  };
244
  /** Whether to render modal inside Portal */
245
  withinPortal?: boolean;
246
  /** Custom styles */
247
  styles?: any;
248
  /** Class names */
249
  classNames?: any;
250
}
251
```