On this page

Notification

Notifications notify the user with the status of an action.

Overview
Rules and guidance
Properties
Styles
Accessibility

When to use

To inform the user about the result of an action they have taken
To inform the user about a system change
To draw the user's attention to something important, timely and relevant to their current task

When not to use

For static contextual information not tied to an action or system event - use plain text instead
For an absence of data - use Empty State instead
While data is loading - use Skeleton Loading instead
For short statuses attached to objects - use Badge instead
More than once per page - Notifications are disruptive. If overused, users will stop noticing them. If multiple are unavoidable, see Grouping below.

Anatomy

Icon
Title
Description
Actions
Close button
Error list - only present in ErrorSummaryNotification

Basic usage

Edit live code

<Notification id="basic-example" title="Meter read being processed">
  <P>It may take up to 60 seconds to appear in the reads table once submitted</P>
</Notification>

Variants and features

Standard variants

Notifications use colour and icons to convey the tone and priority of the information they contain. There are four variants:

Info - provide additional information relevant to the current context
Success - confirm an action was completed as expected
Warning - let the user know they are taking an action that is undesirable, or which might have unexpected results
Error - explain something has gone wrong, and what, if anything, the user can do to correct the problem

The colours and icons are tied to each variant and should not be changed. Do not override the icon or create custom colour combinations - the icon ensures meaning is not communicated by colour alone.

Edit live code

<>
  <Notification id="example-info" variant="info">
    <P>Meter reads take up to 60 seconds to appear in the reads table once submitted</P>
  </Notification>
  <Notification id="example-success" variant="success">
    <P>Meter read submitted</P>
  </Notification>
  <Notification id="example-warning" variant="warning">
    <P>Submitting this meter read will cause this customer to be re-billed</P>
  </Notification>
  <Notification id="example-error" variant="error">
    <P>Meter read not submitted</P>
  </Notification>
</>

Error summary

ErrorSummaryNotification is a separate component used to summarise all validation errors on a form. Always render it on the page and pass errors to it when the form is submitted - it remains hidden until errors are received.

With correct use, the following happens automatically:

Keyboard focus moves to the error summary when it appears
Each listed error links to its respective field

Edit live code

<Inert /* Ignore - prevent auto-focus for this example. */>
  <ErrorSummaryNotification
    id="error-summary"
    errors={[
      { id: 'error-name', message: 'An error message goes here' }
    ]}
  />
</Inert>

In a real form, pass the errors when the form is submitted. The summary stays hidden until it receives them, then takes focus and links to the field:

Edit live code

() => { // ignore - for live code example only.
  const Example = () => {
    const [errors, setErrors] = useState([]);

    const onSubmit = (event) => {
      event.preventDefault();
      setErrors([{ id: 'example', message: 'Enter a name' }]);
    }

    return (
      <>
        <Heading2>Example form</Heading2>
        <ErrorSummaryNotification id="error-summary-dynamic" errors={errors} />
        <form noValidate onSubmit={onSubmit}>
          <Stack spaceBetween={4}>
            <TextField
              id="example"
              label="Name"
              error={getErrorMessage('example', errors)}
            />
            <PrimaryCTAButton type="submit">Show errors</PrimaryCTAButton>
          </Stack>
        </form>
      </>
    );
  }

  return <Example />
}

Dismissal

Notifications are optionally dismissible via the dismissable prop. Do not make a notification dismissible if it is critical for the user to read or interact with, or if they may need to refer back to it during their task.

Use the onDismiss prop to perform an action when the notification is dismissed - for example, updating local storage. Consider whether the notification should be dismissed forever on this device, until the next session, or until the next page load.

Edit live code

<Notification
  id="dismissible-example"
  title="We are processing the meter read"
  dismissable
  onDismiss={() => console.log('Notification dismissed')}
>
  <P>It can take 30 seconds or more to update the account</P>
</Notification>

Single line

For short notifications, title and description can be combined on a single line to save space. Omit the title prop and make the opening words of the description bold, separated from the remaining text by a non-bold hyphen.

Edit live code

<Notification id="single-line-example" variant="success">
  <P><Strong>Meter read submitted</Strong> - it may take 60 seconds to appear in the reads table</P>
</Notification>

Actions

Notifications can include up to two actions. Actions are buttons and should not be used for navigation - use a TextLink in the description instead. Do not use an action for dismissal; use the dismissable prop instead.

Edit live code

<Notification
  id="actions-example"
  title="Meter read being processed"
  actions={[
    {
      label: 'Refresh reads table',
      id: 'refetch',
      onClick: () => alert('Refetch action clicked'),
    },
  ]}>
  <P>It may take up to 60 seconds to appear in the reads table once submitted</P>
</Notification>

Grouping

Use no more than one Notification per page where possible. On pages with multiple independent panels, limit to one per panel.

If multiple notifications in the same place are unavoidable, stack them vertically in order of importance. Never place notifications side by side.

Notification

Also accepts all props from HTMLAttributes.

Name	Type	Default	Required	Description
id	string	—	Yes	Set as the `id` of the notification's wrapper element.
title	ReactNode	—	No	Short bold text shown above the content. The notification renders nothing if it has neither a `title` nor children.
noMargin	boolean	—	No	Removes the default margin below the notification.
variant	error success info warning	'info'	No	The kind of message. Sets the colour and icon, and the default ARIA role (`alert` for `error`, `status` for the rest).
dismissable	boolean	—	No	Shows a dismiss button. Clicking it removes the notification from the page without any state needed from the parent.
onDismiss	() => void	—	No	Called when the user dismisses the notification.
actions	Action[]	—	No	Follow-up actions shown as buttons below the content. Only shown when the notification also has a `title` or children.

ErrorSummaryNotification

Also accepts all props from HTMLAttributes.

Name	Type	Default	Required	Description
id	string	—	Yes	Set as the `id` of the notification's wrapper element.
title	ReactNode	<>There is a problem</>	No	Short bold text shown above the content. The notification renders nothing if it has neither a `title` nor children.
noMargin	boolean	—	No	Removes the default margin below the notification.
dismissable	boolean	—	No	Shows a dismiss button. Clicking it removes the notification from the page without any state needed from the parent.
onDismiss	() => void	—	No	Called when the user dismisses the notification.
actions	Action[]	—	No	Follow-up actions shown as buttons below the content. Only shown when the notification also has a `title` or children.
errors	ErrorSummaryList	—	Yes	The errors to list. Each `message` is shown as a link to the element whose `id` matches the error's `id` (usually the invalid field). While the list is empty the notification renders nothing; when errors arrive it appears with the `title` (`There is a problem` unless set) and takes focus. Keep the same array between renders unless the errors change - a new array moves focus to the notification again.