0
# @mantine/modals
1
2
@mantine/modals is a comprehensive modal management system built on top of Mantine UI components for React applications. It provides a context-based approach to handle modal state management with features including programmatic modal opening/closing, confirmation modals, context modals, and modal updating capabilities.
3
4
## Package Information
5
6
- **Package Name**: @mantine/modals
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @mantine/core @mantine/hooks @mantine/modals`
10
11
## Core Imports
12
13
```typescript
14
import { ModalsProvider, useModals, modals } from "@mantine/modals";
15
import { openModal, closeModal, openConfirmModal, openContextModal } from "@mantine/modals";
16
import type { ContextModalProps, MantineModalsOverride, MantineModals, MantineModal } from "@mantine/modals";
17
```
18
19
For CommonJS:
20
21
```javascript
22
const { ModalsProvider, useModals, openModal, closeModal } = require("@mantine/modals");
23
```
24
25
## Basic Usage
26
27
```typescript
28
import { MantineProvider } from "@mantine/core";
29
import { ModalsProvider, openModal, openConfirmModal } from "@mantine/modals";
30
31
function App() {
32
return (
33
<MantineProvider>
34
<ModalsProvider>
35
<MyComponent />
36
</ModalsProvider>
37
</MantineProvider>
38
);
39
}
40
41
function MyComponent() {
42
const showModal = () => {
43
openModal({
44
title: "Welcome",
45
children: <div>Hello from modal!</div>,
46
});
47
};
48
49
const showConfirm = () => {
50
openConfirmModal({
51
title: "Delete item",
52
children: <div>Are you sure you want to delete this item?</div>,
53
labels: { confirm: "Delete", cancel: "Cancel" },
54
onConfirm: () => console.log("Confirmed"),
55
onCancel: () => console.log("Cancelled"),
56
});
57
};
58
59
return (
60
<div>
61
<button onClick={showModal}>Show Modal</button>
62
<button onClick={showConfirm}>Show Confirm</button>
63
</div>
64
);
65
}
66
```
67
68
## Architecture
69
70
@mantine/modals is built around several key components:
71
72
- **Provider System**: `ModalsProvider` manages global modal state and provides context
73
- **Event System**: Global functions for imperative modal control from anywhere in the app
74
- **Hook API**: `useModals` hook for component-based modal management
75
- **Modal Types**: Support for content, confirmation, and context modals
76
- **Stack Management**: Multiple modals with proper layering and focus management
77
78
## Capabilities
79
80
### Provider Setup
81
82
Modal system initialization and configuration including shared modal properties and custom modal registration.
83
84
```typescript { .api }
85
interface ModalsProviderProps {
86
children?: React.ReactNode;
87
modals?: Record<string, React.FC<ContextModalProps<any>>>;
88
modalProps?: ModalSettings;
89
labels?: ConfirmLabels;
90
}
91
92
function ModalsProvider(props: ModalsProviderProps): JSX.Element;
93
```
94
95
[Provider Setup](./provider-setup.md)
96
97
### Basic Modal Management
98
99
Core modal operations for opening, closing, and updating content modals with custom children.
100
101
```typescript { .api }
102
function openModal(props: ModalSettings): string;
103
function closeModal(id: string): void;
104
function closeAllModals(): void;
105
function updateModal(payload: { modalId: string } & Partial<ModalSettings>): void;
106
```
107
108
[Basic Modal Management](./basic-modals.md)
109
110
### Confirmation Modals
111
112
Specialized modals with confirm/cancel buttons for user confirmations and destructive actions.
113
114
```typescript { .api }
115
function openConfirmModal(props: OpenConfirmModal): string;
116
117
interface OpenConfirmModal extends ModalSettings, ConfirmModalProps {}
118
```
119
120
[Confirmation Modals](./confirm-modals.md)
121
122
### Context Modals
123
124
Predefined reusable modal components registered with the provider for consistent modal experiences.
125
126
```typescript { .api }
127
function openContextModal<TKey extends MantineModal>(
128
payload: OpenContextModal<Parameters<MantineModals[TKey]>[0]['innerProps']> & { modal: TKey }
129
): string;
130
```
131
132
[Context Modals](./context-modals.md)
133
134
### Hook-based Usage
135
136
React hook providing access to modal context methods for component-based modal management.
137
138
```typescript { .api }
139
function useModals(): ModalsContextProps;
140
```
141
142
[Hook-based Usage](./hook-usage.md)
143
144
### Modals Namespace
145
146
Namespace object providing alternative access to modal functions with cleaner naming.
147
148
```typescript { .api }
149
const modals: {
150
open: (props: ModalSettings) => string;
151
close: (id: string) => void;
152
closeAll: () => void;
153
openConfirmModal: (props: OpenConfirmModal) => string;
154
openContextModal: <TKey extends MantineModal>(
155
payload: OpenContextModal<Parameters<MantineModals[TKey]>[0]['innerProps']> & { modal: TKey }
156
) => string;
157
updateModal: (payload: { modalId: string } & Partial<ModalSettings>) => void;
158
updateContextModal: (payload: { modalId: string } & Partial<OpenContextModal<any>>) => void;
159
};
160
```
161
162
## Core Types
163
164
> **Note**: The following types extend Mantine UI component types (`ModalProps`, `ButtonProps`, `GroupProps`) from `@mantine/core`. See [Mantine documentation](https://mantine.dev/) for complete type definitions.
165
166
```typescript { .api }
167
interface ModalSettings extends Partial<Omit<ModalProps, 'opened'>> {
168
modalId?: string;
169
children?: React.ReactNode;
170
title?: React.ReactNode;
171
onClose?: () => void;
172
}
173
174
interface ConfirmLabels {
175
confirm: React.ReactNode;
176
cancel: React.ReactNode;
177
}
178
179
interface ContextModalProps<T extends Record<string, any> = {}> {
180
context: ModalsContextProps;
181
innerProps: T;
182
id: string;
183
}
184
185
interface ModalsContextProps {
186
modalProps: ModalSettings;
187
modals: ModalState[];
188
openModal: (props: ModalSettings) => string;
189
openConfirmModal: (props: OpenConfirmModal) => string;
190
openContextModal: <TKey extends MantineModal>(
191
modal: TKey,
192
props: OpenContextModal<Parameters<MantineModals[TKey]>[0]['innerProps']>
193
) => string;
194
closeModal: (id: string, canceled?: boolean) => void;
195
closeContextModal: <TKey extends MantineModal>(id: TKey, canceled?: boolean) => void;
196
closeAll: () => void;
197
updateModal: (payload: { modalId: string } & Partial<OpenConfirmModal>) => void;
198
updateContextModal: (payload: { modalId: string } & Partial<OpenContextModal<any>>) => void;
199
}
200
201
interface MantineModalsOverride {}
202
203
type MantineModalsOverwritten = MantineModalsOverride extends {
204
modals: Record<string, React.FC<ContextModalProps<any>>>;
205
}
206
? MantineModalsOverride
207
: {
208
modals: Record<string, React.FC<ContextModalProps<any>>>;
209
};
210
211
type MantineModals = MantineModalsOverwritten['modals'];
212
213
type MantineModal = keyof MantineModals;
214
215
type ModalState =
216
| { id: string; props: ModalSettings; type: 'content' }
217
| { id: string; props: OpenConfirmModal; type: 'confirm' }
218
| { id: string; props: OpenContextModal; type: 'context'; ctx: string };
219
220
interface OpenContextModal<CustomProps extends Record<string, any> = {}> extends ModalSettings {
221
innerProps: CustomProps;
222
}
223
224
interface OpenConfirmModal extends ModalSettings, ConfirmModalProps {}
225
226
interface ConfirmModalProps {
227
id?: string;
228
children?: React.ReactNode;
229
onCancel?: () => void;
230
onConfirm?: () => void;
231
closeOnConfirm?: boolean;
232
closeOnCancel?: boolean;
233
cancelProps?: ButtonProps & React.ComponentPropsWithoutRef<'button'> & Record<`data-${string}`, any>;
234
confirmProps?: ButtonProps & React.ComponentPropsWithoutRef<'button'> & Record<`data-${string}`, any>;
235
groupProps?: GroupProps;
236
labels?: ConfirmLabels;
237
}
238
```