Toast

Toasts display brief, temporary notifications of actions, errors, or other events in an application.

Example#

First, render a toast container at the root of your app:

<ToastContainer />

<ToastContainer />

<ToastContainer />

Then, queue a toast from anywhere:

<Button
  onPress={() => ToastQueue.positive('Toast is done!')}
  variant="primary">
  Show toast
</Button>

<Button
  onPress={() => ToastQueue.positive('Toast is done!')}
  variant="primary">
  Show toast
</Button>

<Button
  onPress={() =>
    ToastQueue
      .positive(
        'Toast is done!'
      )}
  variant="primary"
>
  Show toast
</Button>

Content#

Toasts are triggered using one of the methods of ToastQueue. A <ToastContainer> element must be rendered at the root of your app in order to display the queued toasts.

Toasts are shown according to a priority queue, depending on their variant. Actionable toasts are prioritized over non-actionable toasts, and errors are prioritized over other types of notifications. Only one toast is displayed at a time. See the Spectrum design docs for full information on toast priorities.

<ButtonGroup>
  <Button
    onPress={() => ToastQueue.neutral('Toast available')}    variant="secondary">
    Show Neutral Toast
  </Button>
  <Button
    onPress={() => ToastQueue.positive('Toast is done!')}    variant="primary">
    Show Positive Toast
  </Button>
  <Button
    onPress={() => ToastQueue.negative('Toast is burned!')}    variant="negative">
    Show Negative Toast
  </Button>
  <Button
    onPress={() => ToastQueue.info('Toasting…')}    variant="accent"
    style="outline">
    Show Info Toast
  </Button>
</ButtonGroup>

<ButtonGroup>
  <Button
    onPress={() => ToastQueue.neutral('Toast available')}    variant="secondary">
    Show Neutral Toast
  </Button>
  <Button
    onPress={() => ToastQueue.positive('Toast is done!')}    variant="primary">
    Show Positive Toast
  </Button>
  <Button
    onPress={() => ToastQueue.negative('Toast is burned!')}    variant="negative">
    Show Negative Toast
  </Button>
  <Button
    onPress={() => ToastQueue.info('Toasting…')}    variant="accent"
    style="outline">
    Show Info Toast
  </Button>
</ButtonGroup>

<ButtonGroup>
  <Button
    onPress={() =>
      ToastQueue
        .neutral(
          'Toast available'
        )}    variant="secondary"
  >
    Show Neutral Toast
  </Button>
  <Button
    onPress={() =>
      ToastQueue
        .positive(
          'Toast is done!'
        )}    variant="primary"
  >
    Show Positive Toast
  </Button>
  <Button
    onPress={() =>
      ToastQueue
        .negative(
          'Toast is burned!'
        )}    variant="negative"
  >
    Show Negative Toast
  </Button>
  <Button
    onPress={() =>
      ToastQueue.info(
        'Toasting…'
      )}    variant="accent"
    style="outline"
  >
    Show Info Toast
  </Button>
</ButtonGroup>

Internationalization#

To internationalize a Toast, all text content within the toast should be localized. This includes the actionLabel option, if provided. For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of Toast is automatically flipped.

Accessibility#

Toasts are automatically displayed in a landmark region labeled "Notifications". The label can be overridden using the aria-label prop of the ToastContainer element. Landmark regions can be navigated using the keyboard by pressing the F6 key to move forward, and the Shift + F6 key to move backward. This provides an easy way for keyboard users to jump to the toasts from anywhere in the app. When the last toast is closed, keyboard focus is restored.

Events#

Toasts can include an optional action by specifying the actionLabel and onAction options when queueing a toast. In addition, the onClose event is triggered when the toast is dismissed. The shouldCloseOnAction option automatically closes the toast when an action is performed.

<Button
  onPress={() => ToastQueue.info('An update is available', {
    actionLabel: 'Update',
    onAction: () => alert('Updating!'),
    shouldCloseOnAction: true  })}
  variant="primary">
  Show toast
</Button>

<Button
  onPress={() => ToastQueue.info('An update is available', {
    actionLabel: 'Update',
    onAction: () => alert('Updating!'),
    shouldCloseOnAction: true  })}
  variant="primary">
  Show toast
</Button>

<Button
  onPress={() =>
    ToastQueue.info(
      'An update is available',
      {
        actionLabel:
          'Update',
        onAction: () =>
          alert(
            'Updating!'
          ),
        shouldCloseOnAction:
          true      }
    )}
  variant="primary"
>
  Show toast
</Button>

Auto-dismiss#

Toasts support a timeout option to automatically hide them after a certain amount of time. For accessibility, toasts have a minimum timeout of 5 seconds, and actionable toasts will not auto dismiss. In addition, timers will pause when the user focuses or hovers over a toast.

Be sure only to automatically dismiss toasts when the information is not important, or may be found elsewhere. Some users may require additional time to read a toast message, and screen zoom users may miss toasts entirely.

<Button
  onPress={() => ToastQueue.positive('Toast is done!', {timeout: 5000})}  variant="primary">
  Show toast
</Button>

<Button
  onPress={() =>
    ToastQueue.positive('Toast is done!', {
      timeout: 5000
    })}  variant="primary"
>
  Show toast
</Button>

<Button
  onPress={() =>
    ToastQueue
      .positive(
        'Toast is done!',
        {
          timeout: 5000
        }
      )}  variant="primary"
>
  Show toast
</Button>

Programmatic dismissal#

Toasts may be programmatically dismissed if they become irrelevant before the user manually closes them. Each method of ToastQueue returns a function which may be used to close a toast.

function Example() {
  let [close, setClose] = React.useState(null);

  return (
    <Button
      onPress={() => {
        if (!close) {
          let close = ToastQueue.negative('Unable to save', {
            onClose: () => setClose(null)
          });          setClose(() => close);
        } else {
          close();        }
      }}
      variant="primary"
    >
      {close ? 'Hide' : 'Show'} Toast
    </Button>
  );
}

function Example() {
  let [close, setClose] = React.useState(null);

  return (
    <Button
      onPress={() => {
        if (!close) {
          let close = ToastQueue.negative(
            'Unable to save',
            { onClose: () => setClose(null) }
          );          setClose(() => close);
        } else {
          close();        }
      }}
      variant="primary"
    >
      {close ? 'Hide' : 'Show'} Toast
    </Button>
  );
}

function Example() {
  let [close, setClose] =
    React.useState(null);

  return (
    <Button
      onPress={() => {
        if (!close) {
          let close =
            ToastQueue
              .negative(
                'Unable to save',
                {
                  onClose:
                    () =>
                      setClose(
                        null
                      )
                }
              );          setClose(() =>
            close
          );
        } else {
          close();        }
      }}
      variant="primary"
    >
      {close
        ? 'Hide'
        : 'Show'} Toast
    </Button>
  );
}

API#

ToastQueue#

Toast options#

ToastContainer props#