From 694f6e65fb18fb13e22972988844c81618e475bd Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Thu, 13 Apr 2023 16:50:45 +0000 Subject: [PATCH 1/2] clarify toast usage --- docs/api/toast.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/api/toast.md b/docs/api/toast.md index d81ad3ca60d..15bf80749f8 100644 --- a/docs/api/toast.md +++ b/docs/api/toast.md @@ -134,19 +134,17 @@ Toasts are intended to be subtle notifications and are not intended to interrupt ### Screen Readers -`ion-toast` has `aria-live="polite"` and `aria-atomic="true"` set by default. +`ion-toast` has `role="status"` and `aria-live="polite"` set on the inner `.toast-content` element. This causes screen readers to only announce the toast message and header. Buttons and icons will not be announced. -`aria-live` causes screen readers to announce the content of the toast when it is updated. However, since the attribute is set to `'polite'`, screen readers generally do not interrupt the current task. Developers can customize this behavior by using the `htmlAttributes` property to set `aria-live` to `'assertive'`. This will cause screen readers to immediately notify the user when a toast is updated, potentially interrupting any previous updates. +`aria-live` causes screen readers to announce the content of the toast when it is updated. However, since the attribute is set to `'polite'`, screen readers generally do not interrupt the current task. -`aria-atomic="true"` is set to ensure that the entire toast is announced as a single unit. This is useful when dynamically updating the content of the toast as it prevents screen readers from announcing only the content that has changed. +Since toasts are intended to be subtle notification, `aria-live` should never be set to `"assertive"`. If developers need to interrupt the user with an important message, we recommend using an [alert](./alert). ### Tips While this is not a complete list, here are some guidelines to follow when using toasts. -* Do not require user interaction to dismiss toasts. For example, having a "Dismiss" button in the toast is fine, but the toast should also automatically dismiss on its own after a timeout period. If you need user interaction for a notification, consider using [ion-alert](./alert) instead. - -* Avoid opening multiple toasts in quick succession. If `aria-live` is set to `'assertive'`, screen readers may interrupt the reading of the current task to announce the new toast, causing the context of the previous toast to be lost. +* Do not require user interaction to dismiss toasts. For example, having a "Dismiss" button in the toast is fine, but the toast should also automatically dismiss on its own after a timeout period. If you need user interaction for a notification, consider using an [alert](./alert) instead. * For toasts with long messages, consider adjusting the `duration` property to allow users enough time to read the content of the toast. From 388a1bc66bdcff93316026c1a7df855f0204d351 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Fri, 14 Apr 2023 10:26:48 -0400 Subject: [PATCH 2/2] Update toast.md --- docs/api/toast.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/toast.md b/docs/api/toast.md index 15bf80749f8..10a785c2086 100644 --- a/docs/api/toast.md +++ b/docs/api/toast.md @@ -136,7 +136,7 @@ Toasts are intended to be subtle notifications and are not intended to interrupt `ion-toast` has `role="status"` and `aria-live="polite"` set on the inner `.toast-content` element. This causes screen readers to only announce the toast message and header. Buttons and icons will not be announced. -`aria-live` causes screen readers to announce the content of the toast when it is updated. However, since the attribute is set to `'polite'`, screen readers generally do not interrupt the current task. +`aria-live` causes screen readers to announce the content of the toast when it is updated. However, since the attribute is set to `'polite'`, screen readers should not interrupt the current task. Since toasts are intended to be subtle notification, `aria-live` should never be set to `"assertive"`. If developers need to interrupt the user with an important message, we recommend using an [alert](./alert).