0
# Mantine Notifications
1

2
Mantine Notifications is a React-based notification system that provides comprehensive state management for displaying, managing, and customizing notifications in web applications. It offers flexible positioning, queuing when limits are reached, auto-close functionality, and seamless integration with the Mantine UI ecosystem.
3

4
## Package Information
5

6
- **Package Name**: @mantine/notifications
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @mantine/core @mantine/hooks @mantine/notifications`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  notifications,
16
  showNotification,
17
  hideNotification,
18
  updateNotification,
19
  cleanNotifications,
20
  Notifications,
21
  useNotifications
22
} from "@mantine/notifications";
23
```
24

25
For CommonJS:
26

27
```javascript
28
const { 
29
  notifications,
30
  showNotification,
31
  hideNotification,
32
  Notifications 
33
} = require("@mantine/notifications");
34
```
35

36
## Basic Usage
37

38
```typescript
39
import { notifications, Notifications } from "@mantine/notifications";
40
import { MantineProvider } from "@mantine/core";
41

42
// Setup in your app root
43
function App() {
44
  return (
45
    <MantineProvider>
46
      <YourApp />
47
      <Notifications />
48
    </MantineProvider>
49
  );
50
}
51

52
// Show notifications anywhere in your app
53
function YourComponent() {
54
  const handleShowNotification = () => {
55
    notifications.show({
56
      title: 'Success!',
57
      message: 'Data has been saved successfully',
58
      color: 'green',
59
    });
60
  };
61

62
  return <button onClick={handleShowNotification}>Save Data</button>;
63
}
64
```
65

66
## Architecture
67

68
Mantine Notifications is built around several key components:
69

70
- **Store System**: State management using `@mantine/store` for notifications queue and display logic
71
- **React Component**: `Notifications` component that renders notification containers at different screen positions
72
- **Function API**: Multiple usage patterns including direct functions, object methods, and component static methods
73
- **Position System**: Six position options (top/bottom × left/center/right) with independent limit management
74
- **Queue Management**: Automatic queuing when notification limits are exceeded, with queue processing as notifications close
75

76
## Capabilities
77

78
### Store Functions
79

80
Core notification management functions for showing, hiding, updating, and managing notifications programmatically. These functions provide the primary API for notification control.
81

82
```typescript { .api }
83
function showNotification(notification: NotificationData, store?: NotificationsStore): string;
84
function hideNotification(id: string, store?: NotificationsStore): string;
85
function updateNotification(notification: NotificationData, store?: NotificationsStore): string | undefined;
86
function cleanNotifications(store?: NotificationsStore): void;
87
function cleanNotificationsQueue(store?: NotificationsStore): void;
88
function updateNotificationsState(store: NotificationsStore, update: (notifications: NotificationData[]) => NotificationData[]): void;
89
function createNotificationsStore(): NotificationsStore;
90
function useNotifications(store?: NotificationsStore): NotificationsState;
91

92
const notifications: {
93
  show: typeof showNotification;
94
  hide: typeof hideNotification;
95
  update: typeof updateNotification;
96
  clean: typeof cleanNotifications;
97
  cleanQueue: typeof cleanNotificationsQueue;
98
  updateState: typeof updateNotificationsState;
99
};
100

101
const notificationsStore: NotificationsStore;
102
```
103

104
[Store Functions](./store-functions.md)
105

106
### React Component
107

108
The `Notifications` component handles rendering notification containers at different screen positions, with full customization of appearance, behavior, and animations.
109

110
```typescript { .api }
111
interface NotificationsProps extends BoxProps, StylesApiProps<NotificationsFactory>, ElementProps<'div'> {
112
  position?: NotificationPosition;
113
  autoClose?: number | false;
114
  transitionDuration?: number;
115
  containerWidth?: number | string;
116
  limit?: number;
117
  zIndex?: string | number;
118
  store?: NotificationsStore;
119
  withinPortal?: boolean;
120
}
121

122
const Notifications: React.ForwardRefExoticComponent<NotificationsProps & React.RefAttributes<HTMLDivElement>>;
123
```
124

125
[React Component](./react-component.md)
126

127
## Types
128

129
```typescript { .api }
130
// Core notification component props interface from @mantine/core
131
interface NotificationProps extends BoxProps, StylesApiProps<NotificationFactory>, ElementProps<'div', 'title'> {
132
  variant?: string;
133
  onClose?: () => void;
134
  color?: MantineColor;
135
  radius?: MantineRadius;
136
  icon?: React.ReactNode;
137
  title?: React.ReactNode;
138
  children?: React.ReactNode;
139
  loading?: boolean;
140
  withBorder?: boolean;
141
  withCloseButton?: boolean;
142
  closeButtonProps?: Record<string, any>;
143
  loaderProps?: LoaderProps;
144
}
145

146
// Main exported types
147
interface NotificationData extends Omit<NotificationProps, 'onClose'>, Record<`data-${string}`, any> {
148
  id?: string;
149
  position?: NotificationPosition;
150
  message: React.ReactNode;
151
  autoClose?: boolean | number;
152
  onClose?: (props: NotificationData) => void;
153
  onOpen?: (props: NotificationData) => void;
154
}
155

156
interface NotificationsState {
157
  notifications: NotificationData[];
158
  queue: NotificationData[];
159
  defaultPosition: NotificationPosition;
160
  limit: number;
161
}
162

163
type NotificationsStore = MantineStore<NotificationsState>;
164

165
interface NotificationsProps extends BoxProps, StylesApiProps<NotificationsFactory>, ElementProps<'div'> {
166
  position?: NotificationPosition;
167
  autoClose?: number | false;
168
  transitionDuration?: number;
169
  containerWidth?: number | string;
170
  notificationMaxHeight?: number | string;
171
  limit?: number;
172
  zIndex?: string | number;
173
  portalProps?: BasePortalProps;
174
  store?: NotificationsStore;
175
  withinPortal?: boolean;
176
}
177

178
type NotificationsStylesNames = 'root' | 'notification';
179

180
type NotificationsCssVariables = {
181
  root: '--notifications-z-index' | '--notifications-container-width';
182
};
183

184
type NotificationsFactory = Factory<{
185
  props: NotificationsProps;
186
  ref: HTMLDivElement;
187
  stylesNames: NotificationsStylesNames;
188
  vars: NotificationsCssVariables;
189
  staticComponents: {
190
    show: typeof showNotification;
191
    hide: typeof hideNotification;
192
    update: typeof updateNotification;
193
    clean: typeof cleanNotifications;
194
    cleanQueue: typeof cleanNotificationsQueue;
195
    updateState: typeof updateNotificationsState;
196
  };
197
}>;
198

199
// Additional types used in API signatures
200
type NotificationPosition = 
201
  | 'top-left' 
202
  | 'top-right' 
203
  | 'top-center' 
204
  | 'bottom-left' 
205
  | 'bottom-right' 
206
  | 'bottom-center';
207

208
// Types from @mantine/core dependencies
209
type MantineColor = string;
210
type MantineRadius = string | number;
211
type LoaderProps = Record<string, any>;
212
type BoxProps = Record<string, any>;
213
type StylesApiProps<T> = Record<string, any>;
214
type ElementProps<T, K extends string = never> = Record<string, any>;
215
type Factory<T> = T;
216
type MantineStore<T> = Record<string, any>;
217
type BasePortalProps = Record<string, any>;
218

219
// Notification component factory types
220
type NotificationFactory = Factory<{
221
  props: NotificationProps;
222
  ref: HTMLDivElement;
223
  stylesNames: 'root' | 'icon' | 'loader' | 'body' | 'title' | 'description' | 'closeButton';
224
  vars: { root: '--notification-radius' | '--notification-color' };
225
}>;
226
```