Toast Notifications

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 — see Notifications
  • 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.