Toast Notifications

Last updated:

Why toasts are a poor default, what to use instead, and last-resort guidance when you cannot avoid them.

01 — Foundation

Do not use toasts by default

Transient corner pop-ups create accessibility and usability problems — treat them as a last resort, not a default feedback pattern.

Toast notifications are small, temporary messages that appear away from where the user acted — often in a screen corner — and usually auto-dismiss. They are easy to add and hard to get right.

GitHub removed toasts from the Primer design system after sustained accessibility and usability concerns: timing users cannot control, messages disconnected from the triggering UI, missed announcements on large or magnified screens, banner blindness, and keyboard and focus traps when toasts contain actions. See Primer: accessible notifications and messages for the full rationale and recommended alternatives.

On this site, assume you do not need a toast. Most feedback belongs in the UI itself — inline messages, persistent banners, visible state changes, or focused error treatment.

02 — Prefer

Use these before a toast

If the outcome is visible in context, you usually need no extra notification at all.

  • self-evident success — the created item appears in the list; the setting shows as on
  • inline confirmation and status where the action happened — see Confirmation
  • persistent banners for summaries users must be able to re-read — seeNotifications
  • errors and validation next to the field or failed control — see Error States and Accessible Forms
  • loading and completion in the component that initiated the work — see Loading States and Async Actions

03 — Last resort

When a toast might be justified

Only after inline, banner, and in-context options are ruled out.

  • the update is genuinely secondary — users can miss it without losing task progress
  • nothing critical depends on reading the message — not payment, security, destructive, or blocking errors
  • you cannot place feedback next to the trigger without breaking layout or flow — document why in the PR
  • reject proposals that use a toast because it is faster to ship than designing proper in-context feedback

If a toast is the only option left, treat it as a product and accessibility liability you are explicitly accepting — not a neutral UI choice.

04 — If you must

Minimum bar when you cannot avoid one

Auto-dismiss, corner placement, and vague copy fail users — especially under WCAG timing and status-message requirements.

  • do not auto-dismiss until the user dismisses — or provide a clear, keyboard-accessible control to extend time (WCAG 2.2.1)
  • place the live region near the action in the DOM where possible — not only at the document root far from context (WCAG 1.3.2)
  • use role="status" and aria-live="polite"for non-critical updates; avoid spamming assertive announcements
  • keyboard-operable dismiss and any actions inside; manage focus when removing interactive toasts (WCAG 2.1.1)
  • respect reduced motion — no bouncing or dramatic entrance animation
  • distinguish informational, success, warning, and critical — not everything is an emergency
<div role="status" aria-live="polite" aria-atomic="true">
    <p>Invoice exported. <a href="/downloads/">Download file</a></p>
    <button type="button">Dismiss</button>
</div>

Prefer a persistent in-page message over a floating toast even when using live regions — the markup pattern is similar; the placement and persistence are what protect users.

05 — Review

Before you approve

In code review, challenge every toast — most should become inline or banner feedback.

  • alternatives were considered — inline, banner, or visible state change — and documented if rejected
  • the message is not duplicating feedback already visible on the page
  • users can read, dismiss, and act via keyboard; timing is adjustable
  • screen reader announcements are polite, rare, and tied to real status — see Live regions

Default to no toast. When teams reach for one, that is often a sign the underlying flow needs clearer in-context feedback — not another notification layer.

Common questions

Should we use toast notifications by default?

No. Toasts are easy to miss, hard for assistive tech, and often duplicate better patterns. Use inline status, dialog confirmation, or page-level messaging first.

When is a toast acceptable?

Rarely — as a last resort for non-critical background completion when no safer surface exists, with clear text and a path to review the outcome.

What should replace toasts for errors?

Persistent inline error near the source, form summaries, or dedicated status regions — see error states and live regions guidance.