docs(core): add a11y considerations related to @defer()

closes #53466

(cherry picked from commit d2b854b37e)
This commit is contained in:
Danny Koppenhagen 2025-11-07 21:17:01 +01:00 committed by Andrew Kushnir
parent 1e09bdc114
commit f04cf2299b
2 changed files with 31 additions and 0 deletions

View file

@ -151,6 +151,14 @@ The following example shows how to apply the `active-page` class to active links
<!-- vale Angular.Angular_Spelling = NO -->
## 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)

View file

@ -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 users 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
<div aria-live="polite" aria-atomic="true">
@defer (on timer(2000)) {
<user-profile [user]="currentUser" />
} @placeholder {
Loading user profile...
} @loading {
Please wait...
} @error {
Failed to load profile
}
</div>
```
This ensures that changes are announced to the user when transitions (placeholder &rarr; loading &rarr; content/error) occur.