Notifications system

Installation

yarn add @mantine/notifications

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

import '@mantine/core/styles.css';
// ‼️ import notifications styles after core package styles
import '@mantine/notifications/styles.css';

Add the Notifications component anywhere in your application. Note that:

It is required to render the Notifications component inside MantineProvider
You do not need to wrap your application with the 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 />
      {/* Your app here */}
    </MantineProvider>
  );
}

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

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

function Demo() {
  return (
    <Button
      onClick={() =>
        notifications.show({
          title: 'Default notification',
          message: 'Do not forget to star Mantine on GitHub! 🌟',
        })
      }
    >
      Show notification
    </Button>
  );
}

Do not forget to import styles

Have you followed the installation instructions above but something is not working (position prop not working, notifications are stuck at the bottom)? You've fallen into the trap of not importing notification styles! To fix the issue, import notification styles at the root of your application:

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

Functions

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

notifications.show – adds a given notification to the notifications list or queue, depending on the current state and limit
notifications.hide – removes a notification with the given id from the notifications state and queue
notifications.update – updates a notification that was previously added to the state or queue
notifications.promise – shows a loading notification and updates it with success or error state when the given promise settles
notifications.updateState – executes a given callback with current notifications state and queue as an argument and updates state with the 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 the @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 {
  cleanNotifications, // notifications.clean
  cleanNotificationsQueue, // notifications.cleanQueue
  hideNotification, // notifications.hide
  promiseNotification, // notifications.promise
  showNotification, // notifications.show
  updateNotification, // notifications.update
  updateNotificationsState, // notifications.updateState
} from '@mantine/notifications';

Notification props

notifications.show and notifications.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
position – notification position; by default, the value from the position prop of the Notifications component is used
withBorder – determines whether the notification should have a border
withCloseButton – determines whether the close button should be visible
allowClose – determines whether notification can be closed with close button, drag or horizontal scroll swipe, true by default
onClose – called when the notification is unmounted
onOpen – called when the notification is mounted
autoClose – defines timeout in ms after which the notification will be automatically closed; use false to disable auto close
withAutoCloseProgress – determines whether a progress line that fills up until the notification auto closes is displayed at the bottom of the notification; overrides withAutoCloseProgress prop of the Notifications component
priority – display priority used when the number of active notifications exceeds limit; higher numbers are shown first, defaults to 0
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 { XIcon } from '@phosphor-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',
  position: 'bottom-center',
  withCloseButton: true,
  allowClose: true,
  onClose: () => console.log('unmounted'),
  onOpen: () => console.log('mounted'),
  autoClose: 5000,
  withAutoCloseProgress: true,
  title: "You've been compromised",
  message: 'Leave the building immediately',
  color: 'red',
  icon: <XIcon />,
  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

With close button

With border

Color

Radius

Title

Children

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

Dismiss interactions

Notifications can be dismissed by dragging them left or right, or with a horizontal scroll swipe while hovered.

Use allowDragDismiss and allowScrollDismiss on Notifications to disable either interaction:

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

function Demo() {
  return <Notifications allowDragDismiss={false} allowScrollDismiss={false} />;
}

To make a specific notification non-dismissible, set allowClose: false in notifications.show or notifications.update. This hides the close button and disables drag/scroll dismissal for that 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, Group } from '@mantine/core';
import { notifications } from '@mantine/notifications';
import classes from './Demo.module.css';

function Demo() {
  return (
    <Group justify="center">
      <Button
        onClick={() =>
          notifications.show({
            title: 'Notification with custom styles',
            message: 'It is default blue',
            classNames: classes,
          })
        }
      >
        Default notification
      </Button>

      <Button
        color="red"
        onClick={() =>
          notifications.show({
            color: 'red',
            title: 'Notification with custom styles',
            message: 'It is red',
            classNames: classes,
          })
        }
      >
        Error notification
      </Button>
    </Group>
  );
}

Notifications container position

You can define the notification position in the notifications.show function. Possible position values:

top-left
top-right
top-center
bottom-left
bottom-right
bottom-center

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

const positions = [
  'top-left',
  'top-right',
  'bottom-left',
  'bottom-right',
  'top-center',
  'bottom-center',
] as const;

function Demo() {
  const buttons = positions.map((position) => (
    <Button
      key={position}
      onClick={() =>
        notifications.show({
          title: `Notification at ${position}`,
          message: `Notification at ${position} message`,
          position,
        })
      }
    >
      {position}
    </Button>
  ));

  return <Group>{buttons}</Group>;
}

The position can be defined on the Notifications component. In the following example, notifications will be displayed in the top right corner of the screen if position is not defined in the notifications.show function:

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

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

Limit and queue

You can limit the maximum number of notifications that are displayed at a time by setting the 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 a notification from the current state is hidden.

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

function Demo() {
  return (
    <Button
      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>
  );
}

Priority

By default, notifications are distributed between the visible state and the queue in insertion order (FIFO): the first limit notifications are visible and the rest wait in the queue. Set the priority property in notifications.show or notifications.update to control which notifications take the visible slots when there are more active notifications than the limit allows.

Notifications with a higher priority are shown before notifications with a lower one.
Notifications with equal priority keep insertion order (FIFO).
priority defaults to 0, so notifications without it behave exactly as before.
Within the visible set, higher priority notifications are rendered first.

When a high priority notification is added while the visible state is already at limit, it takes a visible slot and the lowest priority visible notification is moved into the queue – even if it was already displayed. Priority is applied independently for each position.

Note that a notification that is moved from the visible state back into the queue is unmounted and mounted again when it returns to a visible slot, so its onOpen callback runs each time it becomes visible.

In the following example the Notifications component uses limit={1}. Show a low priority notification first, then a high priority one: the high priority notification replaces the low priority one, which is moved to the queue and shown again once the high priority notification is closed.

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

// Dedicated store with limit={1} so the priority behavior is easy to see
const store = createNotificationsStore();

function Demo() {
  return (
    <>
      <Notifications store={store} limit={1} position="top-center" />

      <Group justify="center">
        <Button
          color="gray"
          onClick={() =>
            notifications.show(
              {
                title: 'Low priority',
                message: 'I am pushed to the queue when an urgent notification arrives',
                autoClose: false,
                priority: 0,
              },
              store
            )
          }
        >
          Show low priority
        </Button>

        <Button
          color="red"
          onClick={() =>
            notifications.show(
              {
                title: 'High priority',
                message: 'I take the visible slot even when the limit is reached',
                color: 'red',
                autoClose: false,
                priority: 10,
              },
              store
            )
          }
        >
          Show high priority
        </Button>
      </Group>
    </>
  );
}

Remove notifications from state and queue

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

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

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

Use the 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
        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="default" onClick={() => notifications.cleanQueue()}>
        Clean queue
      </Button>

      <Button variant="outline" color="red" onClick={() => notifications.clean()}>
        Clean all
      </Button>
    </Group>
  );
}

Update notification

import { Button } from '@mantine/core';
import { notifications } from '@mantine/notifications';
import { CheckIcon } from '@phosphor-icons/react';

function Demo() {
  return (
    <Button
      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,
          allowClose: 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: <CheckIcon size={18} />,
            loading: false,
            autoClose: 2000,
            allowClose: true,
          });
        }, 3000);
      }}
    >
      Show update notification
    </Button>
  );
}

Promise

Use notifications.promise function to display a loading notification while a promise is pending and update it with success or error state once the promise settles. The function accepts a promise and an object with loading, success and error notifications. success and error can be functions – they receive the resolved value or the rejection reason and return notification props.

State objects accept all notification props except id. notifications.promise applies the following defaults, all of them can be overridden in the corresponding state object:

loading – loading: true, autoClose: false
success – color: 'teal', loading: false, autoClose is reset to the default value
error – color: 'red', loading: false, autoClose is reset to the default value

All three states are displayed in the same notification, props that are not set in the next state are kept from the previous one. For example, if title is set only in loading, it is also displayed in success and error states.

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

function saveDocument(shouldFail: boolean) {
  return new Promise<{ name: string }>((resolve, reject) => {
    setTimeout(() => {
      if (shouldFail) {
        reject(new Error('Network error'));
      } else {
        resolve({ name: 'report.pdf' });
      }
    }, 2000);
  });
}

function Demo() {
  const save = (shouldFail: boolean) =>
    notifications.promise(saveDocument(shouldFail), {
      loading: {
        title: 'Saving document',
        message: 'Please wait, it will take a couple of seconds',
      },
      success: (value) => ({
        title: 'Document saved',
        message: `${value.name} was saved successfully`,
      }),
      error: (error) => ({
        title: 'Failed to save document',
        message: (error as Error).message,
      }),
    });

  return (
    <Group justify="center">
      <Button onClick={() => save(false)}>Save document</Button>
      <Button color="red" onClick={() => save(true)}>
        Save document (fails)
      </Button>
    </Group>
  );
}

notifications.promise returns the promise that was passed to it, so you can await it or chain it. If the loading notification was closed before the promise settled, the success or error state is shown as a new notification. Use id option to reuse the same notification for consecutive calls – when notifications.promise is called with the same id while the previous promise is still pending, the result of the previous promise is ignored:

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

const user = await notifications.promise(saveUser(values), {
  id: 'save-user',
  loading: { message: 'Saving user' },
  success: (savedUser) => ({ message: `${savedUser.name} was saved` }),
  error: { message: 'Failed to save user' },
});

Auto close

You can configure the 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 the 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
        onClick={() => notifications.show({ message: 'I will close in 4 seconds' })}
      >
        Notifications Provider timeout
      </Button>

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

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

Auto close progress

Set withAutoCloseProgress prop on the Notifications component to display a progress line at the bottom of every notification that auto closes. The line fills up over the auto close timeout and reaches 100% right before the notification is closed:

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

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

The Notifications prop sets the default for all notifications, it can be overridden for individual notifications with the withAutoCloseProgress property in notifications.show and notifications.update functions.

Note that:

The progress line is not displayed for notifications with autoClose: false
The progress line fades out when the auto close timer is paused (for example, when the notification is hovered) and fades back in, starting over, when the timer is restarted
The progress line uses notification color
The progress line is a part of the default notification rendering, it is not displayed for notifications rendered with renderNotification
Use progress Styles API selector of the Notifications component to customize the line, for example, to change its height or color

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

function Demo() {
  return (
    <Group justify="center">
      <Button
        onClick={() =>
          notifications.show({
            title: 'Auto close progress',
            message: 'This notification will close in 5 seconds',
            withAutoCloseProgress: true,
            autoClose: 5000,
          })
        }
      >
        Show notification with progress
      </Button>

      <Button
        color="red"
        onClick={() =>
          notifications.show({
            title: 'Something went wrong',
            message: 'Progress line uses notification color',
            color: 'red',
            withAutoCloseProgress: true,
            autoClose: 8000,
          })
        }
      >
        Red notification with progress
      </Button>
    </Group>
  );
}

Pause auto close on hover

By default, hovering over any notification pauses the auto close timer of all visible notifications. You can change this behavior with the pauseResetOnHover prop:

pauseResetOnHover="all" (default) – pauses auto close for all notifications when any notification is hovered
pauseResetOnHover="notification" – pauses auto close only for the hovered notification

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

function Demo() {
  return <Notifications pauseResetOnHover="notification" />;
}

Custom notification rendering

Use renderNotification prop on Notifications component or per notification in notifications.show/notifications.update to completely replace the default notification with custom content. All animations (enter, exit, drag dismiss, scroll dismiss) are preserved for custom notifications:

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

function Demo() {
  return (
    <Group justify="center">
      <Button
        onClick={() =>
          notifications.show({
            autoClose: false,
            renderNotification: (notification) => (
              <div
                style={{
                  display: 'flex',
                  alignItems: 'center',
                  gap: rem(12),
                  padding: rem(16),
                  borderRadius: rem(8),
                  backgroundColor: 'var(--mantine-color-body)',
                  border: '1px solid var(--mantine-color-default-border)',
                  boxShadow: 'var(--mantine-shadow-lg)',
                  userSelect: 'none',
                }}
              >
                <Avatar src={null} radius="xl" color="blue">
                  DM
                </Avatar>
                <div style={{ flex: 1, minWidth: 0 }}>
                  <Text size="sm" fw={600}>
                    Dan sent you a message
                  </Text>
                  <Text size="xs" c="dimmed" lineClamp={1}>
                    Hey, are you free for a quick call?
                  </Text>
                  <Group gap="xs" mt={8}>
                    <Button
                      size="compact-xs"
                      variant="filled"
                      onClick={() =>
                        notifications.hide(notification.id!)
                      }
                    >
                      Reply
                    </Button>
                    <Button
                      size="compact-xs"
                      variant="default"
                      onClick={() =>
                        notifications.hide(notification.id!)
                      }
                    >
                      Dismiss
                    </Button>
                  </Group>
                </div>
              </div>
            ),
            message: '',
          })
        }
      >
        Show custom notification
      </Button>
    </Group>
  );
}

Stacked layout

Set layout="stacked" on the Notifications component to display notifications in a stacked layout where only the latest notification is fully visible, and older notifications peek out behind it.

The stack expands when it is hovered with a mouse, when keyboard focus moves into it, and when it is tapped on a touch device – a tap outside collapses it again. While collapsed, the notifications behind the first one are inert: they are not focusable and are hidden from screen readers.

Note: the stacked demo uses a separate store to avoid affecting other notifications on the page.

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

function Demo() {
  return (
    <>
      {/* Replace your existing Notifications with layout="stacked" */}
      <Notifications layout="stacked" />
      <Group justify="center">
        <Button
          onClick={() => {
            notifications.show({
              title: 'New notification',
              message: 'This notification is part of a stacked layout',
            });
          }}
        >
          Show stacked notification
        </Button>
      </Group>
    </>
  );
}

Subscribe to notifications state

You can subscribe to notification state changes with the useNotifications hook. The hook returns an object with notifications and queue arrays. The notifications array contains all notifications that are currently displayed; queue contains notifications that are waiting to be displayed.

Notifications state

[]

Notifications queue

[]

function Demo() {
  const [counter, { increment }] = useCounter();
  const notificationsStore = useNotifications();

  const showNotification = () => {
    notifications.show({
      title: `Notification ${counter}`,
      message: 'Most notifications are added to queue',
    });

    increment();
  };

  return (
    <>
      <Button onClick={showNotification} mb="md">
        Show notification
      </Button>

      <Text>Notifications state</Text>
      <Code block>{JSON.stringify(notificationsStore.notifications, null, 2)}</Code>

      <Text mt="md">Notifications queue</Text>
      <Code block>{JSON.stringify(notificationsStore.queue, null, 2)}</Code>
    </>
  );
}

JsonViewer

Spotlight