Mantine Notifications

Mantine notifications system

Installation

Source

View source code

Docs

Edit this page

Package

@mantine/notifications

Bundle size

9.3 kB (umd gzipped)

License

MIT

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):

We notify you that

You are now obligated to give a star to Mantine project on Github

We notify you that

You are now obligated to give a star to Mantine project on Github

Disallow close

Color

Title

Children

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>
  );
}