Skip to content
Fuji UI
Component

Toast

Transient feedback. Mount ToastProvider + Toaster once at the app root, then call useToast().add().

Variants

Each toast carries Alert's treatment for its variant - the tone washed in from the leading edge and the icon on its own tile - and each trigger uses the same tone.

With a description

A second line for detail the title cannot carry. timeout overrides the auto-dismiss delay - give a longer message longer to read.

Stacking

Press a few times: toasts stack newest in front, the ones behind pushed up, scaled down and faded, and hovering the stack fans it out.

  • ToastProvider's limit caps how many toasts show at once (3 by default); past it, the oldest drop out of the stack
  • Toaster's position moves the stack along the bottom edge - see Setup below

Setup

Mount the provider and one Toaster viewport once at the app root. Toaster takes position; add() takes an optional description and a timeout (ms; 0 keeps it until dismissed).

  • position takes bottom-right (the default), bottom-center or bottom-left

When to use

  • Brief, self-dismissing confirmation of a completed action - saved, copied, sent.
  • A non-blocking error the user can recover from later, surfaced without interrupting their flow.
  • Reporting the result of an async operation the user kicked off.

When not to use

  • A message the user must act on or must not miss - use Dialog or AlertDialog, which take focus.
  • Persistent status tied to a region or field - use an inline Alert instead.
  • Anything requiring a decision before continuing.

Keyboard

KeyAction
TabReaches the toast's dismiss control while the toast is present.
Enter / SpaceActivates the focused dismiss control (or a custom action).

Accessibility notes

  • New toasts are announced through an aria-live region, so screen readers hear them without focus moving.
  • Auto-dismiss pauses while the stack is hovered or keyboard-focused, so a toast can't disappear mid-read.
  • variant is passed as semantic data (data: { variant }) and maps to a StatusTone - the color is backed by that meaning, not the only signal.

Common mistakes

  • Putting a critical action only inside an auto-dismissing toast - if it vanishes, the action is gone.
  • Very short timeouts on long messages; give the reader time or set timeout: 0 for important ones.
  • Firing many toasts at once instead of relying on the provider's stacking and limit.

Known limitations

  • position and limit are set once, on the Toaster and the provider, not per toast - and every position is along the bottom edge.
  • No built-in undo pattern beyond a custom action you supply in the toast data.

Related components

AlertNotificationDialog
CriterionStatusNote
Live region announcementSupportedNew toasts are announced through an aria-live region without moving focus.
Keyboard dismissSupportedThe dismiss control (and any custom action) is reachable and operable by keyboard.
Auto-dismiss pauseSupportedThe timeout pauses on hover and keyboard focus so a toast can't disappear mid-read.
Status not by color aloneSupportedvariant carries the semantic meaning; the title text conveys it independently of color.
Reduced motionSupportedprefers-reduced-motion: reduce zeroes all Fuji transition durations globally.
Reduced transparencySupportedprefers-reduced-transparency: reduce flattens Glass to opaque surfaces (portals included).
RTL layoutPartialLogical flex/grid gap works under dir="rtl"; directional chevrons are not yet mirrored.

API reference

position"bottom-right"
ToasterPosition

Which bottom corner (or the bottom centre) the stack grows from. Default `"bottom-right"`.

ToastProvider props

Also accepts everything from React.ComponentPropsWithoutRef<typeof import("@base-ui/react/toast").Toast.Provider>.

Coding agents read this reference, with its examples, from the version your project has installed, through the Fuji UI MCP server. Set up your agent