Mantine Notifications

Mantine notifications system
Installation
License

Demo

Usage

Wrap your application with NotificationsProvider. Important: if you use MantineProvider, NotificationsProvider must be placed inside:

import React from 'react';
import { NotificationsProvider } from '@mantine/notifications';
function YourApp() {
return (
<MantineProvider theme={yourTheme}>
<NotificationsProvider>
<App />
</NotificationsProvider>
</MantineProvider>
);
}

Use use-notifications hook at any place in your application:

import React from 'react';
import { Group, Button } from '@mantine/core';
import { useNotifications } from '@mantine/notifications';
function Demo() {
const notifications = useNotifications();
return (
<Group position="center">
<Button
variant="outline"
onClick={() =>
notifications.showNotification({
title: 'Default notification',
message: 'Hey there, your code is awesome! 🤥',
})
}
>
Show notification
</Button>
</Group>
);
}

use-notifications hook

Hook returns object with properties:

  • notifications – list of notifications that are currently displayed
  • queue – list of notifications in queue
  • showNotification – adds given notification to notifications list or queue depending on current state and limit, returns notification id
  • updateNotification – updates notification with given id
  • hideNotification – removes notification with given id from notifications list and queue
  • clean – removes all notifications from notifications list and queue
  • cleanQueue – removes all notifications from queue
function useNotifications(): {
notifications: NotificationProps[];
queue: NotificationProps[];
showNotification(props: NotificationProps): string;
updateNotification(id: string, props: NotificationProps): void;
hideNotification(id: string): void;
clean(): void;
cleanQueue(): void;
};
interface NotificationProps {
id?: string;
color?: string;
className?: string;
style?: React.CSSProperties;
icon?: React.ReactNode;
title?: React.ReactNode;
loading?: boolean;
message: React.ReactNode;
autoClose?: boolean | number;
disallowClose?: boolean;
onClose?(props: NotificationProps): void;
onOpen?(props: NotificationProps): void;
}

Notification props

Notification state item can have these properties:

  • id – notification id, it is used to update adn remove notification, be default id generates randomly
  • disallowClose – removes close button, notification can be closed only programmatically
  • onClose – calls when notification is unmounted
  • onOpen – calls when notification is mounted
  • autoClose – defines timeout in ms on which notification will be automatically closed, use false to disable auto close
  • message – required notification body
  • color, icon, title, className, style, loading – props spread to Notification component

All properties except message are optional.

const notifications = useNotifications();
// Bare minimum – message is required for all notifications
notifications.showNotification({ message: 'Hello' });
// All possible notification props
const id = notifications.showNotification({
id: 'hello-there',
disallowClose: true,
onClose: () => console.log('unmounted'),
onOpen: () => console.log('mounted'),
autoClose: 5000,
title: "You've been compromised",
message: 'Leave the building immediately',
color: 'red',
icon: <Cross1Icon />,
className: 'my-notification-class',
style: { backgroundColor: 'red' },
loading: false,
});

Notifications preview (message prop used as children):

Color

Notifications container position

NotificationsProvider renders notifications container with fixed position inside Portal. Position cannot be changed per notification.

<NotificationsProvider position="top-right" zIndex={2077}>
<YourApp />
</NotificationsProvider>

Limit and queue

NotificationsProvider uses use-queue hook to manage state. You can limit maximum amount of notifications that can be displayed by setting limit prop on NotificationsProvider:

<NotificationsProvider limit={5}>
<YourApp />
</NotificationsProvider>

All notifications added after limit was reached will be added into queue and displayed when notification from current state is closed.

import React from 'react';
import { Group, Button } from '@mantine/core';
import { useNotifications } from '@mantine/notifications';
function Demo() {
const notifications = useNotifications();
return (
<Group position="center">
<Button
variant="outline"
onClick={() => {
Array(10).fill(0).forEach((_, index) => {
setTimeout(() => {
notifications.showNotification({
title: `Notification ${index + 1}`,
message: 'Most notifications are added to queue',
});
}, 200 * index);
});
}}
>
Show 10 notifications
</Button>
</Group>
);
}

Remove notifications from state and queue

To remove specific notification from state or queue use hideNotification handler:

const notifications = useNotifications();
const id = notifications.show({ message: 'Hello!' });
notifications.hideNotification(id);

Use cleanQueue handler to remove all notifications that are not currently displayed and clean handler to remove all notifications from state and queue:

import React from 'react';
import { Group, Button } from '@mantine/core';
import { useNotifications } from '@mantine/notifications';
function Demo() {
const notifications = useNotifications();
return (
<Group position="center">
<Button
variant="outline"
onClick={() => {
Array(10)
.fill(0)
.forEach((_, index) => {
notifications.showNotification({
title: `Notification ${index + 1}`,
message: 'Most notifications are added to queue',
autoClose: false,
});
});
}}
>
Show 10 notifications
</Button>
<Button variant="outline" color="gray" onClick={() => notifications.cleanQueue()}>
Clean queue
</Button>
<Button variant="outline" color="red" onClick={() => notifications.clean()}>
Clean all
</Button>
</Group>
);
}

Update notification

showNotification handler returns notification id, you can use it to update notification:

import React from 'react';
import { Group, Button } from '@mantine/core';
import { useNotifications } from '@mantine/notifications';
import { CheckIcon } from '@modulz/radix-icons';
function Demo() {
const notifications = useNotifications();
return (
<Group position="center">
<Button
variant="outline"
onClick={() => {
const id = notifications.showNotification({
loading: true,
title: 'Loading your data',
message: 'Data will be loaded in 3 seconds, you cannot close this yet',
autoClose: false,
disallowClose: true,
});
setTimeout(() => {
notifications.updateNotification(id, {
id,
color: 'teal',
title: 'Data was loaded',
message:
'Notification will close in 2 seconds, you can close this notification now',
icon: <CheckIcon />,
autoClose: 2000,
});
}, 3000);
}}
>
Show update notification
</Button>
</Group>
);
}

Auto close

You can configure auto close timeout in NotificationsProvider:

// All notifications will be closed automatically in 4000ms
<NotificationsProvider autoClose={4000}>
<YourApp />
</NotificationsProvider>

Or in use-notifications hook handlers:

notifications.showNotification({
message: 'I will close in 500ms seconds',
autoClose: 500,
});
notifications.updateNotification('hello', {
id: 'hello',
message: 'I will never close',
autoClose: false,
});

showNotification and updateNotification have higher priority.

import React from 'react';
import { Group, Button } from '@mantine/core';
import { useNotifications } from '@mantine/notifications';
import { CheckIcon } from '@modulz/radix-icons';
function Demo() {
const notifications = useNotifications();
return (
<Group position="center">
<Button variant="outline" onClick={() =>
notifications.showNotification({ message: 'I will close in 4 seconds' })
}>
Notifications Provider timeout
</Button>
<Button variant="outline" onClick={() =>
notifications.showNotification({ autoClose: 500, message: 'I will close in 500ms' })
}>
Closes in 500ms
</Button>
<Button variant="outline" onClick={() =>
notifications.showNotification({
color: 'blue',
title: 'I will never close',
message: 'unless you click X',
autoClose: false,
})
}>
Never closes automatically
</Button>
</Group>
);
}

React node in notification message

You can render any react node in notification message, for example, input or button. Combine this option with other settings to achieve the desired behavior:

import React from 'react';
import { Group, Button, ActionIcon, TextInput } from '@mantine/core';
import { EnvelopeClosedIcon, PaperPlaneIcon } from '@modulz/radix-icons';
import { EnvelopeClosedIcon } from '@modulz/radix-icons';
function Demo() {
const notifications = useNotifications();
return (
<Group position="center">
<Button
variant="outline"
leftIcon={<EnvelopeClosedIcon />}
onClick={() => {
const id = notifications.showNotification({
autoClose: false,
disallowClose: true,
title: 'Subscribe to email newsletter',
message: (
<>
<div style={{ display: 'flex', paddingTop: 5 }}>
<TextInput
icon={<EnvelopeClosedIcon />}
placeholder="Enter your email"
style={{ flex: 1, marginRight: 15 }}
/>
<ActionIcon
onClick={() => notifications.hideNotification(id)}
size={36}
color="blue"
variant="filled"
>
<PaperPlaneIcon />
</ActionIcon>
</div>
</>
),
});
}}
>
Subscribe to email newsletter
</Button>
</Group>
);
}