Mantine Notifications

Mantine notifications system
Source
View source code
Docs
Edit this page
Package
@mantine/notifications
License
MIT

Installation

Package depends on @mantine/core and @mantine/hooks.

Install with yarn:

yarn add @mantine/notifications

Install with npm:

npm install @mantine/notifications

Demo

Usage

Wrap your application with NotificationsProvider:

import { MantineProvider } from '@mantine/core';
import { NotificationsProvider } from '@mantine/notifications';


function Demo() {
  return (
    <MantineProvider withNormalizeCSS withGlobalStyles>
      <NotificationsProvider>
        <App />
      </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 { IconX } from '@tabler/icons';
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: <IconX />,
  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 Demo() {
  return (
    <NotificationsProvider position="top-right" zIndex={2077}>
      <App />
    </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 Demo() {
  return (
    <NotificationsProvider limit={5}>
      <App />
    </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 { IconCheck } from '@tabler/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: <IconCheck size={16} />,
              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 Demo() {
  return (
    <NotificationsProvider autoClose={4000}>
      <App />
    </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;
}
Go back
Navigation progress – @mantine/nprogress
Up next
Prism code highlight – @mantine/prism

NotificationsProvider component props

NameTypeDescription
autoClose
number | false
Auto close timeout for all notifications, false to disable auto close, can be overwritten for individual notifications by showNotification function
children
ReactNode
Your application
containerWidth
number
Notification width in px, cannot exceed 100%
limit
number
Maximum amount of notifications displayed at a time, other new notifications will be added to queue
notificationMaxHeight
number
Notification max-height in px, used for transitions
position
"bottom-center" | "top-center" | "top-left" | "top-right" | "bottom-left" | "bottom-right"
Notifications position
target
string | HTMLElement
Target element of Portal component
transitionDuration
number
Notification transitions duration, 0 to turn transitions off
zIndex
ZIndex
Notifications container z-index
Build fully functional accessible web applications faster than ever
About
ContributeAbout MantineChangelogReleases
Community
Chat on DiscordFollow on TwitterFollow on GithubGitHub discussions
Project
Mantine UIDocumentationGithub organizationnpm organization
Built by Vitaly Rtishchev and these awesome people
Join Discord community
Follow Mantine on Twitter