useNotifications

Imperative APIs to show and interact with application notifications.

Toolpad core offers a set of abstractions that make it easier to interact with notifications. Notifications are used to give short updates to the user about things that are happening during the application lifetime. They appear at the bottom of the screen. The Toolpad API allows for opening multiple notifications concurrenlty.

First thing you need to do to get access to the notifications APIs is install the NotificationsProvider.

import { NotificationsProvider } from '@toolpad/core/useNotifications';

function App({ children }) {
  return <NotificationsProvider>{children}</NotificationsProvider>;
}

Now you can get acess to the notifications APIs through the useNotifications hook.

import { useNotifications } from '@toolpad/core/useNotifications';

function MyApp() {
  const notifications = useNotifications();
  // ...
}

Basic notification

You can notify your users with a neutral message by calling notifications.show. To have the notification automatically hide, add the autoHideDuration option. This expresses the time in milliseconds after which to close the notification.

notifications.show('Consider yourself notified!', {
  autoHideDuration: 3000,
});

notifications.show('Consider yourself notified!', {
  autoHideDuration: 3000,
});

Press Enter to start editing

Alert notifications

You can send notifications under the form of alerts with the severity property. It takes a value from "info", "success", "warning", or "error".

Severity

InfoSuccessWarningError

notifications.show('Consider yourself notified!', {
  severity,
  autoHideDuration: 3000,
});

notifications.show('Consider yourself notified!', {
  severity,
  autoHideDuration: 3000,
});

Press Enter to start editing

Multiple notifications

Multiple concurrent notifications are stacked and when more than one notification is available, a badge is shown with the amount of open notification. Try it out with the following demo:

notifications.show('Hello', { autoHideDuration: 1000 });
notifications.show('Goodbye', { autoHideDuration: 1000 });

notifications.show('Hello', { autoHideDuration: 1000 });
notifications.show('Goodbye', { autoHideDuration: 1000 });

Press Enter to start editing

Close notifications

You can programmatically close existing notifications. Each notification has an associated key. You can call the notifications.close method with this key to close the opened notification.

Online

const key = online
  ? notifications.show('You are now online', {
      severity: 'success',
      autoHideDuration: 3000,
    })
  : notifications.show('You are now offline', {
      severity: 'error',
    });

return () => {
  notifications.close(key);
};

const key = online
  ? notifications.show('You are now online', {
      severity: 'success',
      autoHideDuration: 3000,
    })
  : notifications.show('You are now offline', {
      severity: 'error',
    });

return () => {
  notifications.close(key);
};

Press Enter to start editing

Dedupe notifications

You can supply your own value for a key to shown notifications to associate them with this key. Notifications with the same key are deduplicated as long as one is already open. If you try to show a notification with the same key, the call is simply ignored.

notifications.show('Listen carefully, I will say this only once', {
  key: 'dedupe-notification',
  autoHideDuration: 5000,
});

notifications.show('Listen carefully, I will say this only once', {
  key: 'dedupe-notification',
  autoHideDuration: 5000,
});

Press Enter to start editing

Scoped notifications

Notification providers can be nested. That way you can scope the notifications to a subset of the page. Use the slots to position the snackbar relative to a specific element on the page.

<NotificationsProvider slots={notificationsProviderSlots}>
  <ScopedContent />
</NotificationsProvider>

<NotificationsProvider slots={notificationsProviderSlots}>
  <ScopedContent />
</NotificationsProvider>

Press Enter to start editing

🚧 Notification center

When multiple notifications are available, click the badge to open the notification center to show a scrollable list of all available notifications. This feature is not available yet.

Hook API

useNotifications()

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

<NotificationsProvider />