Accessible Notifications & Toasts

Notifications go wrong before a single line of ARIA is written, because teams reach for one component, the toast, to carry every kind of message: a quiet confirmation, an urgent error, a time-limited offer, an action the user is meant to take. Those are not the same job, and forcing them into a corner box that fades on a timer is what makes so many notification systems inaccessible. Two questions sort out which pattern you actually need, and almost every other decision in this guide follows from the answers.

The first question is about urgency: can this message wait for the screen reader to finish its current sentence, or must it interrupt? A saved draft or an updated result count can wait, so it belongs in a polite live region. A form submission that failed, or a session about to expire, cannot wait, so it belongs in an assertive one. That is the politeness fork, and it decides between role="status" and role="alert".

The second question is about whether the user has to do something. Is the message fire and forget, like “Draft saved”, or does it carry an action or essential information, like an Undo button, an error to correct, or a warning to act on? Fire-and-forget messages can be toasts that auto-dismiss. Anything the user has to read and act on is not a fire-and-forget toast at all, and putting it on a disappearing timer is the single most common notification failure.

Those two questions map onto three components. A toast is transient and non-modal, announces through a polite region, and never takes focus. An alert banner is persistent and sits in the flow of the page until dismissed or resolved, which suits an error the user must fix. An alert dialog is modal: it interrupts, takes focus, and blocks the rest of the page until answered, and it is built with the dialog pattern, not the toast pattern. The rest of this guide is mostly about building the toast correctly, because that is where the subtle bugs live, but the escape hatch is always there: when a message needs a response, stop reaching for a toast.

This is the bug that silently breaks more toasts than any other, and it has nothing to do with the visible design. A screen reader announces a live region by watching an element that is already in the accessibility tree and speaking whatever text appears inside it. If your code creates a fresh element that carries both the aria-live attribute and the message text in the same operation, the region is usually not being observed yet, and the message is never spoken. The toast slides in, the sighted user sees it, and the screen reader says nothing.

The fix is to separate the container from the content. Put an empty live region into the initial HTML so it is present on page load, and then set or append text into it when an event happens. The container is what has to pre-exist; the message is the change the screen reader reacts to.

<!-- In the initial HTML: present and EMPTY on load.
     This one region is the announcement layer for every toast.
     aria-atomic="false" so only the newly added toast is read,
     not the whole stack, when several are on screen. -->
<div
  id="toast-region"
  aria-live="polite"
  aria-atomic="false"
  class="toast-region"
></div>

const region = document.getElementById("toast-region")

function showToast(message) {
  // The region already exists, so appending a child is a change
  // the screen reader announces. Never create the region in here.
  const toast = document.createElement("div")
  toast.className = "toast"
  toast.textContent = message
  region.appendChild(toast)
  return toast
}

showToast("Draft saved.")

Two more details matter. Never hide the region with display:none or visibility:hidden, because that removes it from the accessibility tree and nothing inside it is announced; if the announcement layer is visually separate from your toasts, hide it with a visually hidden or .sr-only class that keeps the element rendered. And do not flood the region with rapid updates, such as an announcement on every one percent of an upload, which turns the screen reader into a stutter; debounce to meaningful milestones. The 4.1.3 Status Messages reference covers the live-region mechanics in depth; this guide builds the notification component on top of them.

The defining feature of a toast, that it disappears on its own, is also where it collides with accessibility. Removing content on a timer is a time limit, and 2.2.1 Timing Adjustable requires that time limits on content be adjustable unless they are essential. Whether a given toast triggers that criterion depends entirely on the second question from the top of this guide: does the user have to read or act on it?

A pure confirmation is the safe case. “Draft saved” has already been spoken by the live region the instant it appeared, so when the visual fades a few seconds later, nothing is actually lost. That kind of toast can auto-dismiss. Even then, do two things: pause the timer while the pointer is over the toast and while keyboard focus is inside it, so a returning user is not fighting the clock, and always provide a manual close.

// A confirmation toast may auto-dismiss, but pause the timer on
// hover AND on keyboard focus, so it never vanishes while someone
// is reading it or reaching into it.
function autoDismiss(toast, ms) {
  let timer = window.setTimeout(() => toast.remove(), ms)
  const pause = () => window.clearTimeout(timer)
  const resume = () => {
    timer = window.setTimeout(() => toast.remove(), ms)
  }

  toast.addEventListener("mouseenter", pause)
  toast.addEventListener("mouseleave", resume)
  toast.addEventListener("focusin", pause)   // focus entered the toast
  toast.addEventListener("focusout", resume)
}

// Do NOT call this on a toast that holds an action or an error.

There is no universally correct duration. Design systems suggest ranges from a few seconds up to around ten, but those are starting points that assume a short, non-actionable message and an average reader. Longer text needs longer, an action needs no timer at all, and pausing on hover and focus is what turns a guess into something fair.

Real apps fire more than one notification at a time, and how you handle the pile-up matters as much as any single toast. Do not create a separate assertive region for each message; several assertive regions talking over each other is chaos. Keep one polite region as the announcement layer and append each new toast into it, and the screen reader reads the additions in order. Reserve the assertive region for the occasional error.

Visually, cap how many toasts are on screen at once. A tall column of ten stacked toasts is noise for everyone and a wall of tab stops if each has a control. Show a small number, queue the rest, and let them advance as earlier ones dismiss. If toasts persist long enough to be a group, give the stack a role such as regionwith an accessible name like “Notifications” so a screen reader user can find and review them, rather than relying on the single spoken announcement.

Position deserves care too. Toasts usually sit fixed to a corner, and a fixed element can cover the control the user just moved to with the keyboard, which fails 2.4.11 Focus Not Obscured. Keep the toast area clear of interactive content, or shift it when it would overlap what has focus. And because the toast is fixed, check it at 320 pixels wide: it should reflow to fit the viewport, wrap its text, and keep its close button reachable rather than spilling off the edge of a phone screen.

React makes the pre-existing-region rule easy to get wrong, because the natural instinct is to render a toast component only when there is something to show. If the live region is inside that component, it mounts together with its text, and you are back to the silent-toast bug. The pattern that avoids it is a provider mounted once at the app root, whose live region is always in the tree; individual toasts are appended into it as state changes.

// Mounted ONCE at the app root. The live regions are always in
// the tree, so appended toasts are announced in place.
function ToastProvider({ children }) {
  const [toasts, setToasts] = useState([])

  const notify = useCallback((message, options) => {
    const tone = options && options.error ? "error" : "success"
    const id = crypto.randomUUID()
    setToasts((list) => [...list, { id, message, tone }])
  }, [])

  const dismiss = useCallback((id) => {
    setToasts((list) => list.filter((t) => t.id !== id))
  }, [])

  return (
    <ToastContext.Provider value={notify}>
      {children}

      {/* Polite region for confirmations. Present on every render. */}
      <div className="toast-stack" aria-live="polite" aria-atomic="false">
        {toasts
          .filter((t) => t.tone === "success")
          .map((t) => (
            <Toast key={t.id} toast={t} onDismiss={dismiss} />
          ))}
      </div>

      {/* Separate assertive region for errors only. */}
      <div className="toast-stack toast-stack-error" role="alert">
        {toasts
          .filter((t) => t.tone === "error")
          .map((t) => (
            <Toast key={t.id} toast={t} onDismiss={dismiss} />
          ))}
      </div>
    </ToastContext.Provider>
  )
}

Each Toastrenders its message with a leading Success or Error label, a real dismiss button named “Dismiss notification”, and, for confirmations only, a timer that pauses on mouseenter and focusin. Route errors to the assertive region and everything else to the polite one, so urgency is a property of the message rather than an afterthought.

You do not have to hand-build this. Libraries such as react-hot-toast, Sonner, and Radix Toast keep a persistent region mounted for you and handle the announcement plumbing, which is the part that is easy to break. What they cannot decide for you is the politeness of each message, the pause on hover and focus, the named dismiss control, the rule that an actionable toast does not auto-dismiss, and status that does not depend on color. Audit any toast library the same way you would audit your own: turn a screen reader on, trigger a toast, and listen. For the wider set of React patterns, the React accessibility guide covers announcing dynamic changes across the app, and the accessible AI chat guide works the streaming case where announcements arrive continuously.