Skip to content
Mosaic
On this page

Toast

Headless, unstyled notifications stacked in a viewport. Add them with Toast.useToastManager(), or a Toast.createToastManager() instance outside React. They auto-dismiss on a timer that pauses while the viewport is hovered or focused, the window is blurred or the tab is hidden, queue beyond a limit, and announce themselves to screen readers. F6 moves focus to the newest toast and back.

Use for

  • feedback for an action that has no surface of its own, such as a save after its form closed
  • a loading, then success or error, notice for a promise
  • a short confirmation beside the element that caused it, such as Copied
  • showing a notification from outside React

Practices

GuidancePractice
DoRender every toast from useToastManager().toasts, and filter anchored ones with Toast.isAnchored into a Toast.Positioner.
DoHide data-limited toasts with CSS. They stay in the list, inert, while queued.
DoUse manager.promise() for an async action instead of adding and updating toasts by hand. It rethrows a rejection after showing the error toast, so catch it.
DoPass the same id to add to refresh an open toast. It bumps repeatCount and sets data-repeated.
Don’tUse a toast for something the user must answer. Use Dialog, or useConfirmController for a confirm step.
Don’tRender Toast.Arrow outside Toast.Positioner. It throws.

API reference

Toast.Provider

Owns the toast list, timers and queue. Renders no element.

PropTypeDescription
timeoutnumberAuto-dismiss delay in ms. 0 keeps toasts until closed.Default: 5000
limitnumberMost stacked toasts shown at once. Older ones beyond it are marked limited.Default: 3
toastManagerExternalToastManagerA manager from createToastManager(), for adding toasts outside React.

Toast.Portal

Portals its children.

PropTypeDescription
rootHTMLElement | null | RefObject<HTMLElement | null>The element to portal into.Default: the `Portal` container

Toast.Viewport

A div with role="region" and aria-label="Notifications" that holds the stack. Hover or focus inside pauses every timer. Carries data-expanded and --toast-frontmost-height.

Toast.Positioner

Places one toast against an anchor element, outside the stack and the limit. Carries data-side, data-align, data-anchor-hidden and the anchor CSS variables. Fields in toast.positionerProps override its props.

PropTypeDescription
toastToastObjectThe toast from useToastManager().toasts.
anchorElement | nullThe element to sit next to.Default: null
sideToastSideThe side of the anchor. Flips when there is no room.Default: 'top'
alignToastAlignAlignment along that side.Default: 'center'
sideOffsetnumberGap to the anchor in px.Default: 0
alignOffsetnumberShift along the alignment axis in px.Default: 0

Toast.Root

One toast: a focusable div with role="dialog", labelled by its title and described by its description. Escape closes it. Carries data-type, data-expanded, data-limited, data-repeated, data-starting-style and data-ending-style, and --toast-index, --toast-offset-y, --toast-height and --toast-frontmost-height.

PropTypeDescription
toastToastObjectThe toast from useToastManager().toasts.

Toast.Arrow

A FloatingArrow svg pointing at the anchor, inside Toast.Positioner. Carries data-side.

Toast.Content

A layout div. Carries data-behind on toasts behind the frontmost, and data-expanded.

Toast.Title

An h2 that labels the toast. Renders nothing without content.

PropTypeDescription
childrenReact.ReactNodeThe title.Default: toast.title

Toast.Description

A p that describes the toast. Renders nothing without content.

PropTypeDescription
childrenReact.ReactNodeThe description.Default: toast.description

Toast.Action

A button that merges toast.actionProps, runs its onClick, then closes the toast. Renders nothing without action props, children or render.

Toast.Close

A button that closes the toast.

Examples

Stacked toasts

TSX
function ToastList() {
  const { toasts } = Toast.useToastManager();
  return toasts.map(toast => (
    <Toast.Root key={toast.id} toast={toast}>
      <Toast.Content>
        <Toast.Title />
        <Toast.Description />
      </Toast.Content>
      <Toast.Action />
      <Toast.Close aria-label='Close' />
    </Toast.Root>
  ));
}

<Toast.Provider>
  <App />
  <Toast.Portal>
    <Toast.Viewport>
      <ToastList />
    </Toast.Viewport>
  </Toast.Portal>
</Toast.Provider>

Promise

TSX
const manager = Toast.useToastManager();
manager
  .promise(saveProfile(), {
    loading: 'Saving…',
    success: 'Profile saved',
    error: 'Could not save',
  })
  .catch(() => {});