0
# Store Functions
1

2
Core notification management functions for showing, hiding, updating, and managing notifications programmatically. These functions provide the primary API for notification control and can be used in three different patterns.
3

4
## Capabilities
5

6
### Show Notification
7

8
Displays a new notification and returns its unique identifier.
9

10
```typescript { .api }
11
/**
12
 * Display a new notification and return its ID
13
 * @param notification - Notification configuration object
14
 * @param store - Optional custom store instance, defaults to global store
15
 * @returns Generated or provided notification ID
16
 */
17
function showNotification(notification: NotificationData, store?: NotificationsStore): string;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { showNotification, notifications } from "@mantine/notifications";
24

25
// Basic notification
26
const id = showNotification({
27
  message: 'Hello world!',
28
});
29

30
// Notification with title and color
31
showNotification({
32
  title: 'Success',
33
  message: 'Your data was saved successfully',
34
  color: 'green',
35
});
36

37
// Notification with custom position
38
showNotification({
39
  message: 'Top left notification',
40
  position: 'top-left',
41
});
42

43
// Notification with custom auto-close
44
showNotification({
45
  message: 'This closes after 10 seconds',
46
  autoClose: 10000,
47
});
48

49
// Notification with callbacks
50
showNotification({
51
  message: 'Notification with callbacks',
52
  onOpen: (data) => console.log('Opened:', data.id),
53
  onClose: (data) => console.log('Closed:', data.id),
54
});
55

56
// Using the notifications object (same functionality)
57
notifications.show({
58
  message: 'Same as showNotification',
59
});
60
```
61

62
### Hide Notification
63

64
Hides a notification by its ID and triggers its onClose callback.
65

66
```typescript { .api }
67
/**
68
 * Hide a notification by its ID
69
 * @param id - Notification ID to hide
70
 * @param store - Optional custom store instance, defaults to global store
71
 * @returns The provided notification ID
72
 */
73
function hideNotification(id: string, store?: NotificationsStore): string;
74
```
75

76
**Usage Examples:**
77

78
```typescript
79
import { showNotification, hideNotification, notifications } from "@mantine/notifications";
80

81
// Show and later hide
82
const id = showNotification({
83
  message: 'I will be hidden manually',
84
  autoClose: false,
85
});
86

87
// Hide after 3 seconds
88
setTimeout(() => {
89
  hideNotification(id);
90
}, 3000);
91

92
// Using the notifications object
93
setTimeout(() => {
94
  notifications.hide(id);
95
}, 3000);
96
```
97

98
### Update Notification
99

100
Updates an existing notification with new properties.
101

102
```typescript { .api }
103
/**
104
 * Update an existing notification with new properties
105
 * @param notification - Notification data with ID and properties to update
106
 * @param store - Optional custom store instance, defaults to global store
107
 * @returns The notification ID or undefined if not found
108
 */
109
function updateNotification(notification: NotificationData, store?: NotificationsStore): string | undefined;
110
```
111

112
**Usage Examples:**
113

114
```typescript
115
import { showNotification, updateNotification, notifications } from "@mantine/notifications";
116

117
// Show initial notification
118
const id = showNotification({
119
  id: 'status-update',
120
  message: 'Processing...',
121
  color: 'blue',
122
  loading: true,
123
  autoClose: false,
124
});
125

126
// Update with success
127
setTimeout(() => {
128
  updateNotification({
129
    id: 'status-update',
130
    message: 'Completed successfully!',
131
    color: 'green',
132
    loading: false,
133
    autoClose: 3000,
134
  });
135
}, 2000);
136

137
// Using the notifications object
138
notifications.update({
139
  id: 'status-update',
140
  message: 'Updated message',
141
});
142
```
143

144
### Clean Notifications
145

146
Removes all currently displayed notifications and clears the queue.
147

148
```typescript { .api }
149
/**
150
 * Remove all notifications and clear the queue
151
 * @param store - Optional custom store instance, defaults to global store
152
 */
153
function cleanNotifications(store?: NotificationsStore): void;
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
import { cleanNotifications, notifications } from "@mantine/notifications";
160

161
// Clear all notifications
162
cleanNotifications();
163

164
// Using the notifications object
165
notifications.clean();
166
```
167

168
### Clean Notifications Queue
169

170
Removes only the queued notifications, keeping currently displayed ones.
171

172
```typescript { .api }
173
/**
174
 * Remove queued notifications only, keep displayed ones
175
 * @param store - Optional custom store instance, defaults to global store
176
 */
177
function cleanNotificationsQueue(store?: NotificationsStore): void;
178
```
179

180
**Usage Examples:**
181

182
```typescript
183
import { cleanNotificationsQueue, notifications } from "@mantine/notifications";
184

185
// Clear only the queue
186
cleanNotificationsQueue();
187

188
// Using the notifications object
189
notifications.cleanQueue();
190
```
191

192
### Update Notifications State
193

194
Low-level function to update the notification state with custom logic.
195

196
```typescript { .api }
197
/**
198
 * Update notification state with custom logic
199
 * @param store - Store instance to update
200
 * @param update - Function that receives current notifications and returns updated array
201
 */
202
function updateNotificationsState(
203
  store: NotificationsStore, 
204
  update: (notifications: NotificationData[]) => NotificationData[]
205
): void;
206
```
207

208
**Usage Examples:**
209

210
```typescript
211
import { updateNotificationsState, notificationsStore, notifications } from "@mantine/notifications";
212

213
// Custom state update logic
214
updateNotificationsState(notificationsStore, (current) => {
215
  // Remove all error notifications
216
  return current.filter(notification => notification.color !== 'red');
217
});
218

219
// Using the notifications object
220
notifications.updateState(notificationsStore, (current) => {
221
  // Mark all notifications as non-auto-closing
222
  return current.map(notification => ({ ...notification, autoClose: false }));
223
});
224
```
225

226
### Store Management
227

228
Functions for creating and managing notification store instances.
229

230
```typescript { .api }
231
/**
232
 * Create a new notifications store instance
233
 * @returns New store instance with default state
234
 */
235
function createNotificationsStore(): NotificationsStore;
236

237
/**
238
 * Default global notifications store instance
239
 */
240
const notificationsStore: NotificationsStore;
241

242
/**
243
 * React hook to subscribe to notifications state
244
 * @param store - Store instance to subscribe to, defaults to global store
245
 * @returns Current notifications state
246
 */
247
function useNotifications(store?: NotificationsStore): NotificationsState;
248
```
249

250
**Usage Examples:**
251

252
```typescript
253
import { 
254
  createNotificationsStore, 
255
  notificationsStore, 
256
  useNotifications,
257
  showNotification 
258
} from "@mantine/notifications";
259

260
// Create custom store for isolated notifications
261
const customStore = createNotificationsStore();
262

263
// Use custom store
264
showNotification({
265
  message: 'Custom store notification'
266
}, customStore);
267

268
// Hook to get notifications state
269
function NotificationStatus() {
270
  const state = useNotifications();
271
  
272
  return (
273
    <div>
274
      Active: {state.notifications.length}, 
275
      Queued: {state.queue.length}
276
    </div>
277
  );
278
}
279

280
// Hook with custom store
281
function CustomStoreStatus() {
282
  const state = useNotifications(customStore);
283
  return <div>Custom store notifications: {state.notifications.length}</div>;
284
}
285
```
286

287
## Types
288

289
```typescript { .api }
290
interface NotificationData extends Omit<NotificationProps, 'onClose'>, Record<`data-${string}`, any> {
291
  /** Notification id, can be used to close or update notification */
292
  id?: string;
293
  /** Position of the notification, if not set, uses Notifications component position */
294
  position?: NotificationPosition;
295
  /** Notification message, required for all notifications */
296
  message: React.ReactNode;
297
  /** Auto close timeout in ms, or false to disable, overrides component autoClose */
298
  autoClose?: boolean | number;
299
  /** Called when notification closes */
300
  onClose?: (props: NotificationData) => void;
301
  /** Called when notification opens */
302
  onOpen?: (props: NotificationData) => void;
303
}
304

305
interface NotificationsState {
306
  /** Currently displayed notifications */
307
  notifications: NotificationData[];
308
  /** Queued notifications waiting to be displayed */
309
  queue: NotificationData[];
310
  /** Default position for notifications without explicit position */
311
  defaultPosition: NotificationPosition;
312
  /** Maximum number of notifications displayed simultaneously */
313
  limit: number;
314
}
315

316
type NotificationsStore = MantineStore<NotificationsState>;
317
```