Mantine Notifications

Mantine notifications system

Source

View source code

Docs

Edit this page

Package

@mantine/notifications

Bundle size

0 kB (umd gzipped)

License

MIT

Installation

Package depends on react, react-dom, @mantine/hooks, @mantine/core and react-jss.

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. Important: if you use MantineProvider, NotificationsProvider must be placed inside:

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

Build fully functional accessible web applications with ease

Project

Contribute to Mantine Changelog Releases

Community

Join Discord community Follow on Twitter Email newsletter Github discussions

Feedback

Your feedback is most valuable contribution to the project, please share how you use Mantine, what features are missing and what is done good

Leave feedback

Built by Vitaly Rtishchev and these awesome people

Join Discord community

Follow Mantine on Twitter