Toast

A Toast displays a brief, temporary notification of actions, errors, or other events in an application.

import {MyToastRegion, queue} from './Toast';
import {Button} from './Button';

function Example(props) {
  return (
    <div>
      <MyToastRegion />
      <Button onPress={() => queue.add(
        {
          title: props.title || 'Files uploaded',
          description: props.description || '3 files uploaded successfully.'
        },
        props.timeout ? {timeout: props.timeout} : undefined
      )}>
        Show Toast
      </Button>
    </div>
  );
}

Content

Title and description

Use the "title" and "description" slots within <ToastContent> to provide structured content for the toast. The title is required, and description is optional.

import {queue} from './Toast';
import {Button} from './Button';

function Example() {
  return (
    <Button
      onPress={() => queue.add({
        title: 'Update available',
        description: 'A new version is ready to install.'
      })}
    >
      Check for updates
    </Button>
  );
}

Close button

Include a <Button slot="close"> to allow users to dismiss the toast manually. This is important for accessibility.

Dismissal

Use the timeout option to automatically dismiss toasts after a period of time. For accessibility, toasts should have a minimum timeout of 5 seconds. Timers automatically pause when the user focuses or hovers over a toast.

import {queue} from './Toast';
import {Button} from './Button';

function Example() {
  return (
    <Button
      onPress={() => queue.add(
        {title: 'File has been saved!'},
        {timeout: 5000}
      )}
    >
      Save file
    </Button>
  );
}

Programmatic dismissal

Toasts can be programmatically dismissed using the key returned from queue.add(). This is useful when a toast becomes irrelevant before the user manually closes it.

import {queue} from './Toast';
import {Button} from './Button';
import {useState} from 'react';

function Example() {
  let [toastKey, setToastKey] = useState<string | null>(null);

  return (
    <Button
      onPress={() => {
        if (!toastKey) {
          setToastKey(queue.add(
            {title: 'Processing...'},
            {onClose: () => setToastKey(null)}
          ));
        } else {
          queue.close(toastKey);
        }
      }}
    >
      {toastKey ? 'Cancel' : 'Process'}
    </Button>
  );
}

Accessibility

Toast regions are landmark regions that can be navigated using F6 to move forward and Shift + F6 to move backward. This provides an easy way for keyboard users to jump to toasts from anywhere in the app.

When a toast is closed, focus moves to the next toast if any. When the last toast is closed, focus is restored to where it was before.

API

<ToastRegion>
  {({toast}) => (
    <Toast toast={toast}>
      <ToastContent>
        <Text slot="title" />
        <Text slot="description" />
      </ToastContent>
      <Button slot="close" />
    </Toast>
  )}
</ToastRegion>

ToastRegion

Default className: react-aria-ToastRegion

Toast

Default className: react-aria-Toast

ToastContent

<ToastContent> renders the main content of a toast, including the title and description slots. It accepts all HTML attributes.

ToastQueue

A ToastQueue manages the state for a <ToastRegion>. The state is stored outside React so you can trigger toasts from anywhere in your application.

Properties

Methods