Screen Reader Optimization Template

Prioritize VoiceOver with Safari on macOS and NVDA with Chrome on Windows. These two combinations cover the majority of screen reader users in the 2025 WebAIM survey. If you can only test with one, use NVDA with Chrome because it is free, runs on the most common OS (Windows), and Chrome is the most popular browser. The [accessibility compliance template](/templates/accessibility-compliance-template) includes a decision matrix for choosing your test matrix based on your user demographics.

SPAs create unique challenges because page navigations do not trigger a full page load event. Screen readers do not automatically announce the new page. Three things need to happen on every client-side route change: update `document.title` to reflect the new page, move focus to the main content area or page heading, and optionally announce the page transition via an `aria-live` region. The [focus management template](/templates/focus-management-template) covers the focus restoration pattern in detail.

Use visually hidden text (`.sr-only` or `clip-path` technique) when the visual context provides information that the audio context lacks. Examples: a star rating that shows 4 filled stars needs `.sr-only` text saying "4 out of 5 stars." An icon button needs `.sr-only` text or `aria-label` describing the action. However, do not add hidden text as a band-aid for poor structure. If a heading or label is needed, make it visible rather than hiding it.

Content inserted via CSS `::before` and `::after` pseudo-elements with the `content` property is announced by all major screen readers. This means decorative CSS content (arrows, bullets, icons via `content: "\2022"`) will be read aloud. Use `content: "" / ""` with `aria-hidden="true"` on the parent or the pseudo-element to suppress the announcement, or use SVG icons with `aria-hidden="true"` instead of CSS content.

Both provide an accessible name. `aria-label` takes a string value directly. `aria-labelledby` takes one or more element IDs and reads their text content as the label. `aria-labelledby` is preferred when visible text exists because it stays in sync automatically. `aria-label` is preferred when no visible text exists. Note that `aria-label` on non-interactive elements (like `<div>` or `<span>`) is inconsistently supported. Use it on interactive elements (buttons, inputs, links, landmarks) where support is reliable. The [ARIA checklist template](/templates/aria-checklist-template) covers the full set of ARIA attributes and their correct usage.