Mantine Notifications

Mantine notifications system
License

Installation

Install with npm:

npm install @mantine/notifications @mantine/core @mantine/hooks

Install with yarn:

yarn add @mantine/notifications @mantine/core @mantine/hooks

Demo

Usage

Wrap your application with NotificationsProvider:

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

Then use showNotification function anywhere in your application:

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

Functions

Notifications system is based on custom events, @mantine/notifications package exports the following functions:

  • showNotification – adds given notification to notifications list or queue depending on current state and limit
  • updateNotification – updates notification that was previously added to the state or queue
  • hideNotification – removes notification with given id from notifications state and queue
  • cleanNotifications – removes all notifications from notifications state and queue
  • cleanNotificationsQueue – removes all notifications from queue

All functions can be imported from @mantine/notifications package and can be used in any part of your application:

import { showNotification } from '@mantine/notifications';

Notification props

Notification state item can have these properties:

  • id – notification id, it is used to update and remove notification, by default id is randomly generated
  • 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, radius, className, style, sx, loading – props spread to Notification component

All properties except message are optional.

import { showNotification } from '@mantine/notifications';
// Bare minimum – message is required for all notifications
showNotification({ message: 'Hello' });
// Most used notification props
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' },
sx: { backgroundColor: 'red' },
loading: false,
});

Notifications preview (message prop used as children):

Color
Radius
xs
sm
md
lg
xl

Customize notification styles

You can use sx, style, className or Styles API classNames, styles props to customize notification styles:

import { Group, Button } from '@mantine/core';
import { showNotification } from '@mantine/notifications';
function Demo() {
return (
<Group position="center">
<Button
variant="outline"
onClick={() =>
showNotification({
title: 'Default notification',
message: 'Hey there, your code is awesome! 🤥',
styles: (theme) => ({
root: {
backgroundColor: theme.colors.blue[6],
borderColor: theme.colors.blue[6],
'&::before': { backgroundColor: theme.white },
},
title: { color: theme.white },
description: { color: theme.white },
closeButton: {
color: theme.white,
'&:hover': { backgroundColor: theme.colors.blue[7] },
},
}),
})
}
>
Show customized notification
</Button>
</Group>
);
}

Notifications container position

NotificationsProvider renders notifications container with fixed position inside Portal. Position cannot be changed per notification. NotificationsProvider supports the following positions:

  • top-left
  • top-right
  • top-center
  • bottom-left
  • bottom-right
  • bottom-center
import { NotificationsProvider } from '@mantine/notifications';
function App() {
return (
<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:

import { NotificationsProvider } from '@mantine/notifications';
function App() {
return (
<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 { Group, Button } from '@mantine/core';
import { showNotification } from '@mantine/notifications';
function Demo() {
return (
<Group position="center">
<Button
variant="outline"
onClick={() => {
Array(10).fill(0).forEach((_, index) => {
setTimeout(() => {
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 function:

import { showNotification, hideNotification } from '@mantine/notifications';
showNotification({ id: 'hello', message: 'Hello!' });
hideNotification('hello');

Use cleanNotificationsQueue function to remove all notifications that are not currently displayed and cleanNotifications function to remove all notifications from state and queue:

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

Update notification

import { Group, Button } from '@mantine/core';
import { showNotification, updateNotification } from '@mantine/notifications';
import { CheckIcon } from '@modulz/radix-icons';
function Demo() {
return (
<Group position="center">
<Button
variant="outline"
onClick={() => {
showNotification({
id: 'load-data',
loading: true,
title: 'Loading your data',
message: 'Data will be loaded in 3 seconds, you cannot close this yet',
autoClose: false,
disallowClose: true,
});
setTimeout(() => {
updateNotification({
id: 'load-data',
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 with NotificationsProvider:

import { NotificationsProvider } from '@mantine/notifications';
// All notifications will be closed automatically in 4000ms
function App() {
return (
<NotificationsProvider autoClose={4000}>
<YourApp />
</NotificationsProvider>
);
}

Or in showNotification/updateNotification functions:

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

showNotification and updateNotification functions autoClose prop always has higher priority.

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

use-notifications hook

To subscribe to notifications state use useNotifications hook, it returns object with the following properties:

  • notifications – array of notifications that are currently displayed
  • queue – array of notifications in queue
function useNotifications(): {
notifications: NotificationProps[];
queue: NotificationProps[];
};
interface NotificationProps {
id?: string;
color?: string;
radius?: MantineNumberSize;
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;
}