Alert

Accessibility

Toast notifications often appear away from what triggered them, may time out automatically, and can be hard to discover in linear reading order. That creates accessibility and usability risk.

Industry guidance

GitHub’s Primer design system documentation states that toasts pose significant accessibility concerns and are not recommended for use. They recommend more established patterns when users must read, understand, or act on information. Read the full discussion in Accessible notifications and messages.

Toasts sit in tension with several WCAG success criteria, including:

• 1.3.2 Meaningful Sequence - DOM order vs. the control that triggered the message
• 2.2.1 Timing Adjustable - Timed dismissal
• 2.1.1 Keyboard - Interactive controls in the toast
• 4.1.3 Status Messages - How updates are exposed to assistive technology.

Toasts in RHDS

RhAlert.toast() exposes toasts as polite status messages (role="status", aria-live="polite"), not as role="alert" interruptions. Focus does not move into the toast when it opens; keyboard users Tab to it to use dismiss or actions. See Alert accessibility for details.

If you still use a toast in RHDS, follow these guidelines:

• Prefer persistent: true when the message matters or users need time to read or use controls.
  • Timed toasts clear after about eight seconds.
  • Offering a non-timer path (persistent or dismiss) aligns better with WCAG 2.2.1.
• Keep copy short.
  • Do not put critical errors only in a toast when the user must fix something.
  • Use an inline alert, banner, or dialog instead.
• Toasts are always dismissible in RHDS.
  • Any actions inside a toast must be keyboard-operable. For tab order and focus behavior shared with inline alerts, see Alert accessibility.

When to use other patterns

Prefer other patterns when the user must read, understand, or act on important information—for example:

• For critical or blocking errors, use an inline alert, banner, or dialog (persistent until addressed where appropriate).
• For complex or multi-step outcomes, use a summary banner or progressive disclosure, not a short auto-dismissing message alone.
• For long-running tasks, use a persistent notification, banner, email, or another channel the user can return to.
• For a simple success that is already obvious in the UI, often no toast is needed.

Usability concerns

• Corner placement can be easy to miss on large displays or under screen magnification.
• Auto-dismiss and tab switching can cause users to lose the message.
• Stacked toasts can obscure primary actions such as submit buttons; see Style — Stacking.
• Toasts are visually separate from what triggered them, which weakens proximity—reinforce important outcomes in context when you can.

Authoring

Do not author <rh-alert variant="toast"> directly in HTML. Use RhAlert.toast() so grouping, animation, and persistence stay consistent.

For do and don’t code comparisons, options tables, and implementation samples, see Examples.

Stacking

When multiple toasts fire in sequence, they stack and reflow as each closes. See Style for annotated visuals.

Other libraries

To learn more about our other libraries, visit the getting started page.