Skip to content

Commit d2b854b

Browse files
d-koppenhagenAndrewKushnir
authored andcommitted
docs(core): add a11y considerations related to @defer()
closes angular#53466
1 parent 1651908 commit d2b854b

2 files changed

Lines changed: 31 additions & 0 deletions

File tree

adev/src/content/best-practices/a11y.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,14 @@ The following example shows how to apply the `active-page` class to active links
151151

152152
<!-- vale Angular.Angular_Spelling = NO -->
153153

154+
## Deferred Loading
155+
156+
When using Angular's `@defer` blocks for lazy loading content, consider the accessibility implications for users with assistive technologies.
157+
Screen readers may not automatically announce content changes when deferred components load, potentially leaving users unaware of new content.
158+
159+
To ensure deferred content changes are properly announced, wrap your `@defer` blocks in elements with appropriate ARIA live regions.
160+
For detailed guidance and examples, see the [accessibility section in the defer guide](/guide/templates/defer#keep-accessibility-in-mind).
161+
154162
## More information
155163

156164
- [Accessibility - Google Web Fundamentals](https://developers.google.com/web/fundamentals/accessibility)

adev/src/content/guide/templates/defer.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -360,3 +360,26 @@ When you have nested `@defer` blocks, they should have different triggers in ord
360360
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).
361361

362362
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.
363+
364+
### Keep accessibility in mind
365+
366+
When using `@defer` blocks, consider the impact on users with assistive technologies like screen readers.
367+
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.
368+
369+
To ensure deferred content changes are announced to screen readers, you can wrap your `@defer` block in an element with a live region:
370+
371+
```angular-html
372+
<div aria-live="polite" aria-atomic="true">
373+
@defer (on timer(2000)) {
374+
<user-profile [user]="currentUser" />
375+
} @placeholder {
376+
Loading user profile...
377+
} @loading {
378+
Please wait...
379+
} @error {
380+
Failed to load profile
381+
}
382+
</div>
383+
```
384+
385+
This ensures that changes are announced to the user when transitions (placeholder &rarr; loading &rarr; content/error) occur.

0 commit comments

Comments
 (0)