Notifications system

Mantine notifications system

License

Installation

yarn add @mantine/notifications

After installation import package styles at the root of your application:

import '@mantine/notifications/styles.css';

Add Notifications component anywhere in your application. Note that:

  • It is required to render Notifications component inside MantineProvider
  • You do not need to wrap your application with Notifications component – it is not a provider, it is a regular component
  • You should not render multiple Notifications components – if you do that, your notifications will be duplicated
import { MantineProvider } from '@mantine/core';
import { Notifications } from '@mantine/notifications';

function Demo() {
  return (
    <MantineProvider>
      <Notifications />
      <App />
    </MantineProvider>
  );
}

All set! You can now use all notifications system features.

import { Button } from '@mantine/core';
import { notifications } from '@mantine/notifications';

function Demo() {
  return (
    <Button
      variant="outline"
      onClick={() =>
        notifications.show({
          title: 'Default notification',
          message: 'Hey there, your code is awesome! 🤥',
        })
      }
    >
      Show notification
    </Button>
  );
}

Functions

@mantine/notifications package exports notifications object with the following functions:

  • notifications.show – adds given notification to the notifications list or queue, depending on the current state and limit
  • notifications.hide – removes notification with given id from the notifications state and queue
  • notifications.update – updates notification that was previously added to the state or queue
  • notifications.updateState – executes given callback with current notifications state and queue as an argument and updates state with returned value
  • notifications.clean – removes all notifications from the notifications state and queue
  • notifications.cleanQueue – removes all notifications from the queue

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

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

You can also import these functions separately:

// alias functions
import {
  showNotification, // notifications.show
  hideNotification, // notifications.hide
  updateNotification, // notifications.update
  updateNotificationsState, // notifications.updateState
  cleanNotifications, // notifications.clean
  cleanNotificationsQueue, // notifications.cleanQueue
} from '@mantine/notifications';

Notification props

notifications.show and notification.update functions can be called with an object that has the following properties:

  • id – notification id, it is used to update and remove notifications, by default id is randomly generated
  • withBorder – determines whether notification should have a border
  • withCloseButton – determines whether the close button should be visible
  • 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, loading – props passed down to the Notification component

All properties except message are optional.

import { IconX } from '@tabler/icons-react';
import { notifications } from '@mantine/notifications';

// Bare minimum – message is required for all notifications
notifications.show({ message: 'Hello' });

// Most used notification props
notifications.show({
  id: 'hello-there',
  withCloseButton: 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' },
  loading: false,
});

Notifications preview (message prop used as children):

Color
Radius
import { Notification } from '@mantine/core';

function Demo() {
  return (
    <Notification title="We notify you that">
      You are now obligated to give a star to Mantine project on GitHub
    </Notification>
  );
}

Customize notification styles

You can use style, className or Styles API classNames, styles props to customize notification styles. Usually, it is better to override Notification styles with classNames prop in the theme object.

import { Button } from '@mantine/core';
import { notifications } from '@mantine/notifications';
import classes from './Demo.module.css';

function Demo() {
  return (
    <Button
      variant="outline"
      onClick={() =>
        notifications.show({
          title: 'Notification with custom styles',
          message: 'It is default blue',
          classNames: classes,
        })
      }
    >
      Show customized notification
    </Button>
  );
}

Notifications container position

Notifications container has fixed position inside, it is rendered inside Portal by default. Position cannot be changed per notification. Notifications supports the following positions:

  • top-left
  • top-right
  • top-center
  • bottom-left
  • bottom-right
  • bottom-center
import { Notifications } from '@mantine/notifications';

function Demo() {
  return <Notifications position="top-right" zIndex={1000} />;
}

Limit and queue

You can limit maximum number of notifications that are displayed at a time by setting limit prop on Notifications:

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

function Demo() {
  return <Notifications limit={5} />;
}

All notifications added after the limit was reached are added to the queue and displayed when notification from current state is hidden.

import { Button } from '@mantine/core';
import { notifications } from '@mantine/notifications';

function Demo() {
  return (
    <Button
      variant="outline"
      onClick={() => {
        Array(10).fill(0).forEach((_, index) => {
          setTimeout(() => {
            notifications.show({
              title: `Notification ${index + 1}`,
              message: 'Most notifications are added to queue',
            });
          }, 200 * index);
        });
      }}
    >
      Show 10 notifications
    </Button>
  );
}

Remove notifications from state and queue

To remove specific notification from state or queue use notifications.hide function:

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

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

Use notifications.cleanQueue function to remove all notifications from the queue and notifications.clean to remove all notifications both from the state and queue:

import { Group, Button } from '@mantine/core';
import { notifications } from '@mantine/notifications';

function Demo() {
  return (
    <Group justify="center">
      <Button
        variant="outline"
        onClick={() => {
          Array(10)
            .fill(0)
            .forEach((_, index) => {
              notifications.show({
                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

import { Button, rem } from '@mantine/core';
import { notifications } from '@mantine/notifications';
import { IconCheck } from '@tabler/icons-react';

function Demo() {
  return (
    <Button
      variant="outline"
      onClick={() => {
        const id = notifications.show({
          loading: true,
          title: 'Loading your data',
          message: 'Data will be loaded in 3 seconds, you cannot close this yet',
          autoClose: false,
          withCloseButton: false,
        });

        setTimeout(() => {
          notifications.update({
            id,
            color: 'teal',
            title: 'Data was loaded',
            message: 'Notification will close in 2 seconds, you can close this notification now',
            icon: <IconCheck style={{ width: rem(18), height: rem(18) }} />,
            loading: false,
            autoClose: 2000,
          });
        }, 3000);
      }}
    >
      Show update notification
    </Button>
  );
}

Auto close

You can configure auto close timeout with Notifications:

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

// All notifications will be closed automatically in 4000ms
function Demo() {
  return <Notifications autoClose={4000} />;
}

Or per notification in notifications.show/notifications.update functions:

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

notifications.show({
  message: 'I will close in 500ms seconds',
  autoClose: 500,
});

notifications.update({
  id: 'hello',
  message: 'I will never close',
  autoClose: false,
});

notifications.show and notifications.update functions autoClose prop has higher priority.

import { Group, Button } from '@mantine/core';
import { notifications } from '@mantine/notifications';

function Demo() {
  return (
    <Group justify="center">
      <Button
        variant="outline"
        onClick={() => notifications.show({ message: 'I will close in 4 seconds' })}
      >
        Notifications Provider timeout
      </Button>

      <Button
        variant="outline"
        onClick={() =>
          notifications.show({
            message: 'I will close in 500ms',
            autoClose: 500,
          })
        }
      >
        Closes in 500ms
      </Button>

      <Button
        variant="outline"
        onClick={() =>
          notifications.show({
            color: 'blue',
            title: 'I will never close',
            message: 'unless you click X',
            autoClose: false,
          })
        }
      >
        Never closes automatically
      </Button>
    </Group>
  );
}