diff --git a/adev/src/content/best-practices/a11y.md b/adev/src/content/best-practices/a11y.md index e8116ad353e..6494bbd477d 100644 --- a/adev/src/content/best-practices/a11y.md +++ b/adev/src/content/best-practices/a11y.md @@ -151,6 +151,14 @@ The following example shows how to apply the `active-page` class to active links +## Deferred Loading + +When using Angular's `@defer` blocks for lazy loading content, consider the accessibility implications for users with assistive technologies. +Screen readers may not automatically announce content changes when deferred components load, potentially leaving users unaware of new content. + +To ensure deferred content changes are properly announced, wrap your `@defer` blocks in elements with appropriate ARIA live regions. +For detailed guidance and examples, see the [accessibility section in the defer guide](/guide/templates/defer#keep-accessibility-in-mind). + ## More information - [Accessibility - Google Web Fundamentals](https://developers.google.com/web/fundamentals/accessibility) diff --git a/adev/src/content/guide/templates/defer.md b/adev/src/content/guide/templates/defer.md index 82382369aa7..3182991f010 100644 --- a/adev/src/content/guide/templates/defer.md +++ b/adev/src/content/guide/templates/defer.md @@ -342,3 +342,26 @@ When you have nested `@defer` blocks, they should have different triggers in ord Avoid deferring components that are visible in the user’s viewport on initial load. Doing this may negatively affect Core Web Vitals by causing an increase in cumulative layout shift (CLS). In the event this is necessary, avoid `immediate`, `timer`, `viewport`, and custom `when` triggers that cause the content to load during the initial page render. + +### Keep accessibility in mind + +When using `@defer` blocks, consider the impact on users with assistive technologies like screen readers. +Screen readers that focus on a deferred section will initially read the placeholder or loading content, but may not announce changes when the deferred content loads. + +To ensure deferred content changes are announced to screen readers, you can wrap your `@defer` block in an element with a live region: + +```angular-html +