Notification

Import

import { Notification } from '@contentful/f36-components';
// or
import { Notification } from '@contentful/f36-notification';

Examples

Basic

Hide code
function NotificationBasicExample() {
  return (
    <Button
      variant="secondary"
      onClick={() => Notification.success('The entry is published!')}
    >
      Show notification
    </Button>
  );
}
Open in Playground

Intent

The Notification component can be configured in a number of different ways. Here is a guide to when to use certain variations.

Hide code
function NotificationIntentsExample() {
  return (
    <Stack justifyContent="center" flexWrap="wrap">
      <Button
        variant="positive"
        onClick={() => Notification.success('This is a success notification')}
      >
        Show success notification
      </Button>
      <Button
        variant="negative"
        onClick={() => Notification.error('This is an error notification')}
      >
        Show error notification
      </Button>
      <Button
        variant="secondary"
        onClick={() => Notification.warning('This is a warning notification')}
      >
        Show warning notification
      </Button>
      <Button
        variant="primary"
        onClick={() => Notification.info('This is an info notification')}
      >
        Show info notification
      </Button>
    </Stack>
  );
}
Open in Playground

Placement

Hide code
function NotificationPlacementExample() {
  return (
    <Stack>
      <Button
        variant="secondary"
        onClick={() => {
          Notification.setPlacement('top');
          Notification.success('Notification message at the top');
        }}
      >
        Top notification
      </Button>
      <Button
        variant="secondary"
        onClick={() => {
          Notification.setPlacement('bottom');
          Notification.success('Notification message at the bottom');
        }}
      >
        Bottom notification
      </Button>
    </Stack>
  );
}
Open in Playground

With title

Hide code
function NotificationTitleExample() {
  return (
    <Button
      variant="secondary"
      onClick={() =>
        Notification.success('The entry is published!', { title: 'All good!' })
      }
    >
      Show notification
    </Button>
  );
}
Open in Playground

Sticky notification

If you want to disabled auto-closing behavior, you can pass 0 as duration of the notification.

Hide code
function NotificationStickyExample() {
  return (
    <Button
      variant="secondary"
      onClick={() =>
        Notification.warning(
          'This message will be dismissed only after clicking the "Close" button!',
          { duration: 0 },
        )
      }
    >
      Show sticky notification
    </Button>
  );
}
Open in Playground

Using unique id

If you want to make sure that the same notification appears only once at any given time, you can specify a custom notification id.

Hide code
function NotificationUniqueIdExample() {
  // Try clicking on the button several times
  return (
    <Button
      variant="secondary"
      onClick={() =>
        Notification.error('System error!', { id: 'system-error' })
      }
    >
      Show unique notification
    </Button>
  );
}
Open in Playground

Using call to action

You call append an additional call to action to all notificataion by using cta property.

The common use case is undo button.

Hide code
function NotificationCtaExample() {
  return (
    <Button
      variant="secondary"
      onClick={() => {
        const notification = Notification.success('The entry is published!', {
          cta: {
            label: 'Undo',
            textLinkProps: {
              variant: 'primary',
              onClick: () => {
                notification.then((item) => {
                  Notification.close(item.id);
                  console.log('undo');
                });
              },
            },
          },
        });
      }}
    >
      Show notification with CTA
    </Button>
  );
}
Open in Playground

All main intent functions (success, error, and warning) have the following type declaration:

type NotificationAction = (
  text: string,
  settings?: {
    // you can specify a custom notification duration
    // tip: use 0 to make your notification sticky
    duration?: number;
    // whether notification has close button or not
    withClose?: boolean;
    // custom id, by default the unique id is generated automatically
    // by specifying custom id, you can make sure
    // that the specific notification is present only once at any given moment
    id?: string;
    // Additional header title of the notification
    title?: string;
    // Call to action properties
    // For example, your notification can have `Undo` button
    cta?: Partial<{
      label: string;
      textLinkProps: Partial<TextLinkProps>;
    }>;
  },
) => Notification;

By default, the notification closes after 6s, but when the user hovers (mouse overs) the notification it will stop the countdown timer and the toast will stay alive as long as the toast is being hovered.

// closing one notification
const notification = await Notification.success('hello');
Notification.close(notification.id);

// In some situations toasts might become outdated before they expire.
// In those situations you can use `Notification.closeAll()` to close all open toasts.
Notification.closeAll();

// change placement for all notifications
// (default is bottom and offset is 20)
Notification.setPlacement('top', { offset: 100 });
Notification.setPlacement('bottom', { offset: 0 });

// change duration of expiration change placement for all notifications
// (default is 6000ms)
Notification.setDuration(1000); // 1 second
Notification.setDuration(100000); // 100 seconds

Content guidelines

• Don't confuse Notification with Note, which persist in the UI and do not dismiss
• Use clear and succinct copy, since the notification will only be available for 6 seconds
• Use active voice, present tense, and consider tone of voice depending on the circumstance
• Use sentence style caps (in which only the first word of a sentence or term is capitalized)