diff --git a/site/src/content/docs/components/toasts.mdx b/site/src/content/docs/components/toasts.mdx index cb6afb9d6f36..8597f2f00d24 100644 --- a/site/src/content/docs/components/toasts.mdx +++ b/site/src/content/docs/components/toasts.mdx @@ -262,6 +262,10 @@ You can also get fancy with flexbox utilities to align toasts horizontally and/o Toasts are intended to be small interruptions to your visitors or users, so to help those with screen readers and similar assistive technologies, you should wrap your toasts in an [`aria-live` region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions). Changes to live regions (such as injecting/updating a toast component) are automatically announced by screen readers without needing to move the user’s focus or otherwise interrupt the user. Additionally, include `aria-atomic="true"` to ensure that the entire toast is always announced as a single (atomic) unit, rather than just announcing what was changed (which could lead to problems if you only update part of the toast’s content, or if displaying the same toast content at a later point in time). If the information needed is important for the process, e.g. for a list of errors in a form, then use the [alert component]([[docsref:/components/alerts]]) instead of toast. + +Toasts work best for optional, non-critical updates that users can ignore. If a message requires immediate attention, blocks progress, or asks the user to take action, use a more persistent pattern such as an [alert]([[docsref:/components/alerts]]) instead. + + Note that the live region needs to be present in the markup *before* the toast is generated or updated. If you dynamically generate both at the same time and inject them into the page, they will generally not be announced by assistive technologies. You also need to adapt the `role` and `aria-live` level depending on the content. If it’s an important message like an error, use `role="alert" aria-live="assertive"`, otherwise use `role="status" aria-live="polite"` attributes.