Toast

The Toast component has been designed with accessibility in mind, providing a non-intrusive way to display temporary notifications to users. It follows accessibility best practices to ensure all users, including those using assistive technologies, can perceive and understand these notifications.

These attributes are passed through the ariaProps object in the second argument of the createToast function:

createToast("Your message", {
  ariaProps: {
    role: "alert",
    "aria-live": "assertive",
  },
});

• Focus management: Toasts do not steal focus from the user’s current task, maintaining keyboard navigation flow
• Animation pausing: Hover over toasts pauses the dismissal countdown, giving users more time to read lengthy messages

• Visual notifications: Toasts appear visually and are automatically announced to screen readers
• Keyboard focus: Toasts don’t steal keyboard focus, allowing users to continue their current task
• Mouse hover: Pauses the toast dismissal timer
• Mouse leave: Resumes the toast dismissal timer

• Keep messages concise: Use clear, brief messages that can be quickly read and understood
• Use appropriate roles:
  • Use role="status" for non-critical information (default)
  • Use role="alert" only for important messages requiring immediate attention
• Set appropriate aria-live values:
  • Use aria-live="assertive" only for critical messages, interrupts the current task to announce the message
  • Use aria-live="polite" for most messages (default), waits for finish of prioritized announcements
  • Use aria-live="off" for toasts that are not so urgent, announces the message once current task is finished and trigger element still has focus (if exists)
• Avoid too many toasts: Limit the number of simultaneous toast notifications to prevent overwhelming users
• Consider message duration: Set an appropriate dismissTimeout based on message length and importance
• Provide context: Ensure messages make sense when announced out of context by screen readers
• Translation: Ensure all toast content is properly localized for international users

import { createToast } from "@kiwicom/orbit-components/lib/Toast";
createToast("Your changes have been saved");

Screen reader announces: “Your changes have been saved” (with default role="status" and aria-live="polite")

import { createToast } from "@kiwicom/orbit-components/lib/Toast";
import AlertCircle from "@kiwicom/orbit-components/lib/icons/AlertCircle";
createToast("Payment unsuccessful. Please try again.", {
  icon: <AlertCircle />,
  ariaProps: {
    role: "alert",
    "aria-live": "assertive",
  },
});

Screen reader announces immediately: “Payment unsuccessful. Please try again.”

import { createToastPromise } from "@kiwicom/orbit-components/lib/Toast";
createToastPromise(
  saveDataPromise,
  {
    loading: "Saving your changes...",
    success: "Changes saved successfully",
    error: "Failed to save changes",
  },
  {
    // Global aria props for all states
    ariaProps: {
      role: "status",
      "aria-live": "polite",
    },
    // Override aria props for error state
    error: {
      ariaProps: {
        role: "alert",
        "aria-live": "assertive",
      },
    },
  },
);

Screen reader announces the appropriate message based on the promise state, with the error state having higher priority.