0
# Accessibility Announcements
1
2
ARIA-live region announcements for screen reader accessibility. Provides a system for announcing dynamic content changes to assistive technology users.
3
4
**Note**: The announce module is not exported through the main package index and must be imported directly.
5
6
## Import
7
8
```typescript
9
import { announce, AnnouncerPriority, DATA_MDC_DOM_ANNOUNCE } from '@material/dom/announce';
10
```
11
12
## Capabilities
13
14
### Announce Function
15
16
Announces messages to screen readers via ARIA-live regions.
17
18
```typescript { .api }
19
/**
20
* Announces the given message with optional priority, defaulting to "polite"
21
* @param message - The message to announce to screen readers
22
* @param options - Configuration options for the announcement
23
*/
24
function announce(message: string, options?: AnnouncerMessageOptions): void;
25
```
26
27
### Announcement Options
28
29
Configuration options for controlling announcement behavior.
30
31
```typescript { .api }
32
interface AnnouncerMessageOptions {
33
/**
34
* The priority level for the announcement
35
* @default AnnouncerPriority.POLITE
36
*/
37
priority?: AnnouncerPriority;
38
39
/**
40
* The document context for the announcement
41
* @default document
42
*/
43
ownerDocument?: Document;
44
}
45
```
46
47
### Announcement Priorities
48
49
Priority levels that control how screen readers handle announcements.
50
51
```typescript { .api }
52
enum AnnouncerPriority {
53
/**
54
* Polite announcements wait for the user to finish their current activity
55
* This is the default and recommended for most use cases
56
*/
57
POLITE = 'polite',
58
59
/**
60
* Assertive announcements interrupt the user's current activity
61
* Use sparingly for urgent messages like errors
62
*/
63
ASSERTIVE = 'assertive'
64
}
65
```
66
67
### Data Attribute Constant
68
69
The data attribute used to identify announcement live regions.
70
71
```typescript { .api }
72
/**
73
* Data attribute added to live region elements for identification
74
*/
75
const DATA_MDC_DOM_ANNOUNCE: 'data-mdc-dom-announce';
76
```
77
78
## Usage Examples
79
80
### Basic Announcements
81
82
```typescript
83
import { announce } from '@material/dom/announce';
84
85
// Simple polite announcement (default)
86
announce('Form saved successfully');
87
88
// Equivalent explicit polite announcement
89
announce('Form saved successfully', {
90
priority: AnnouncerPriority.POLITE
91
});
92
```
93
94
### Urgent Announcements
95
96
```typescript
97
import { announce, AnnouncerPriority } from '@material/dom/announce';
98
99
// Assertive announcement for errors
100
announce('Error: Please correct the highlighted fields', {
101
priority: AnnouncerPriority.ASSERTIVE
102
});
103
104
// Network error announcement
105
announce('Connection lost. Attempting to reconnect...', {
106
priority: AnnouncerPriority.ASSERTIVE
107
});
108
```
109
110
### Document Context
111
112
```typescript
113
import { announce } from '@material/dom/announce';
114
115
// Announce in iframe context
116
const iframe = document.querySelector('iframe');
117
const iframeDoc = iframe.contentDocument;
118
119
announce('Content loaded in iframe', {
120
ownerDocument: iframeDoc
121
});
122
123
// Announce in modal dialog context
124
const modal = document.querySelector('.modal');
125
const modalDoc = modal.ownerDocument;
126
127
announce('Modal opened', {
128
ownerDocument: modalDoc
129
});
130
```
131
132
### Form Validation
133
134
```typescript
135
import { announce, AnnouncerPriority } from '@material/dom/announce';
136
137
function validateForm(form: HTMLFormElement) {
138
const errors = findValidationErrors(form);
139
140
if (errors.length > 0) {
141
const errorMessage = `${errors.length} validation error${errors.length > 1 ? 's' : ''} found`;
142
announce(errorMessage, {
143
priority: AnnouncerPriority.ASSERTIVE
144
});
145
} else {
146
announce('Form is valid and ready to submit');
147
}
148
}
149
```
150
151
### Dynamic Content Updates
152
153
```typescript
154
import { announce } from '@material/dom/announce';
155
156
class SearchResults {
157
updateResults(results: any[]) {
158
this.renderResults(results);
159
160
// Announce results to screen readers
161
const count = results.length;
162
if (count === 0) {
163
announce('No results found');
164
} else {
165
announce(`${count} result${count > 1 ? 's' : ''} found`);
166
}
167
}
168
169
showLoadingState() {
170
announce('Searching...');
171
}
172
173
showError(error: string) {
174
announce(`Search error: ${error}`, {
175
priority: AnnouncerPriority.ASSERTIVE
176
});
177
}
178
}
179
```
180
181
### Progress Updates
182
183
```typescript
184
import { announce } from '@material/dom/announce';
185
186
class FileUpload {
187
updateProgress(percent: number) {
188
// Update visual progress bar
189
this.progressBar.style.width = `${percent}%`;
190
191
// Announce progress at intervals
192
if (percent % 25 === 0) {
193
announce(`Upload ${percent}% complete`);
194
}
195
}
196
197
onComplete() {
198
announce('File upload completed successfully');
199
}
200
201
onError(error: string) {
202
announce(`Upload failed: ${error}`, {
203
priority: AnnouncerPriority.ASSERTIVE
204
});
205
}
206
}
207
```
208
209
## Accessibility Guidelines
210
211
### When to Use Announcements
212
213
**Good use cases:**
214
- Form validation results
215
- Content loading completion
216
- Search result counts
217
- Error messages
218
- Status changes
219
- Progress updates
220
221
**Avoid announcements for:**
222
- Every user interaction
223
- Redundant information already in focus
224
- Overly frequent updates
225
- Purely decorative changes
226
227
### Priority Guidelines
228
229
**POLITE (default):**
230
- Success messages
231
- Content updates
232
- Search results
233
- Progress milestones
234
- Non-critical status changes
235
236
**ASSERTIVE (use sparingly):**
237
- Error messages
238
- Network failures
239
- Invalid form submissions
240
- Time-sensitive alerts
241
- Critical system messages
242
243
### Message Guidelines
244
245
**Write clear, concise messages:**
246
```typescript
247
// Good
248
announce('3 items added to cart');
249
250
// Too verbose
251
announce('The user has successfully added three items to their shopping cart and can now proceed to checkout');
252
```
253
254
**Include relevant context:**
255
```typescript
256
// Good
257
announce('Page 2 of 5 loaded');
258
259
// Missing context
260
announce('Page loaded');
261
```
262
263
**Use consistent language:**
264
```typescript
265
// Consistent
266
announce('Form saved');
267
announce('Form deleted');
268
269
// Inconsistent
270
announce('Form has been saved successfully');
271
announce('Deletion complete');
272
```
273
274
## Implementation Details
275
276
### Live Region Management
277
278
The announcer automatically creates and manages ARIA-live regions:
279
280
- Creates separate regions for polite and assertive announcements
281
- Regions are positioned off-screen but accessible to screen readers
282
- Regions are marked with `aria-atomic="true"` for complete message reading
283
- Regions are reused across multiple announcements for efficiency
284
285
### Screen Reader Compatibility
286
287
The implementation works with major screen readers:
288
289
- **NVDA**: Requires brief timeout before content update
290
- **VoiceOver**: Handles immediate content updates
291
- **JAWS**: Compatible with both priorities
292
- **Dragon**: Works with voice navigation
293
294
### Cross-Document Support
295
296
Supports announcements in different document contexts:
297
298
- Main document announcements
299
- Iframe document announcements
300
- Modal dialog document contexts
301
- Multiple document management per announcer instance
302
303
### Performance Considerations
304
305
- Uses singleton pattern to minimize memory usage
306
- Lazy creation of live regions
307
- Automatic cleanup of disconnected regions
308
- Click listener cleanup to prevent memory leaks