Toast | A11y Context

Selection

The criteria an agent checks before retrieving this component.

Use when

Use when presenting a temporary, non-blocking status message.
Use when the message confirms an action (e.g., "Saved", "Added to watchlist").
Use when the message is text-only and contains no required actions, except for (at most) a dismiss button.

Try a different component when

Do not use when the message requires user acknowledgment, moves keyboard focus, or blocks background interaction (use dialog.basic).
Do not use when the message is urgent or must interrupt the user immediately (use dialog.alert).
Do not use when the message includes required actions or interactive controls beyond simple dismissal (use snackbar).

Must Haves

Non-negotiable structure. Every generated instance must satisfy these rules.

The live region container must be present in the DOM when the page/view loads.
The toast message must be announced via role="status", or an equivalent such as aria-live="polite" and aria-atomic="true".
When a toast is triggered, its message text must be injected into the existing live region container.
The toast must not move focus automatically when it appears.
The toast must disappear automatically (recommended ~5 seconds).
The live region text must be cleared when the toast dismisses to avoid stale messages being discovered later.
If a dismiss button is present, it must not steal focus when the toast appears.

Donts

Avoid these accessibility and UX barriers.

Do not mount/unmount the live region container based on toast visibility.
Do not move focus into the toast when it appears.
Do not use role="alertdialog".
The toast must not contain buttons or elements that require user action (use snackbar or dialog instead).

Customizable

Alternatives and options that give the AI agent some room to move.

Visual placement (top-right, bottom-center, etc.).
Duration (within reasonable non-disruptive bounds).
Whether a dismiss button is included.
Styling (color, elevation, animation).

Golden Pattern

The tested reference implementation. Agents start from this shape and adapt to the developer’s codebase and context.

JSX
"use client";

const ToastContext = createContext(() => {});

export function ToastProvider({ children }) {
  const [message, setMessage] = useState("");
  const timeoutRef = useRef(null);

  const showToast = useCallback((text) => {
    if (timeoutRef.current) window.clearTimeout(timeoutRef.current);
    setMessage(text);
    timeoutRef.current = window.setTimeout(() => setMessage(""), 5000);
  }, []);

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

      {/* Live region is always mounted */}
      <div role="status" aria-atomic="true">
        {message}
      </div>
    </ToastContext.Provider>
  );
}

export function useToast() {
  return useContext(ToastContext);
}

/** Demo */
export function ToastDemo() {
  const toast = useToast();

  return (
    <div>
      <button type="button" onClick={() => toast("Saved successfully.")}>
        Save
      </button>
    </div>
  );
}

Acceptance Checks

The component’s test spec — an optional body of checks for verification.

Keyboard

Trigger a toast via keyboard.
Focus remains on the triggering control.
No focus is moved into the toast.

Screen Reader

When triggered, the message is announced once as a polite status update.
The message is not announced repeatedly.
After the toast auto-dismisses, the live region is cleared (stale text is not discoverable later).
Triggering a new toast replaces the previous announcement.

Selection​

Use when

Try a different component when

Must Haves​

Donts​

Customizable​

Golden Pattern​

Acceptance Checks​