Skip to main content
Skip to docs content

Examples

Common HTML patterns and their predicted screen reader output. Each example shows the HTML input and what NVDA, VoiceOver, and Narrator would announce. For the full programmatic API behind these predictions, see the API Reference.

Button with aria-label

A button using aria-label overrides the visible text content for screen readers.

HTML
<button aria-label="Submit payment">Pay now</button>
NVDA Output
"Submit payment, button"
VoiceOver Output
"Submit payment, button"
Narrator Output
"Submit payment, button"

Navigation landmark

A nav element with aria-label creates a named navigation landmark. Each screen reader announces landmarks differently.

HTML
<nav aria-label="Main">
  <a href="/">Home</a>
  <a href="/about">About</a>
</nav>
NVDA Output
"Main, navigation landmark
  Home, link
  About, link"
VoiceOver Output
"navigation, Main
  Home, link
  About, link"
Narrator Output
"navigation, Main
  link, Home
  link, About"

Form with labels

Properly associated labels are announced before the input type.

HTML
<label for="email">Email address</label>
<input type="email" id="email" />
NVDA Output
"Email address, edit"
VoiceOver Output
"Email address, edit text"
Narrator Output
"Email address, edit"

Heading hierarchy

Headings are announced with their level. Screen readers let users navigate by heading level, so proper hierarchy matters.

HTML
<h1>Welcome</h1>
<h2>Getting Started</h2>
<h3>Installation</h3>
NVDA Output
"Welcome, heading level 1
Getting Started, heading level 2
Installation, heading level 3"
VoiceOver Output
"heading level 1, Welcome
heading level 2, Getting Started
heading level 3, Installation"
Narrator Output
"Heading level 1, Welcome
Heading level 2, Getting Started
Heading level 3, Installation"

Checkbox with states

Checkboxes announce their checked state. NVDA uses "not checked", VoiceOver uses "unchecked", and Narrator uses "unchecked" / "partially selected" for mixed state.

HTML
<input type="checkbox" id="terms" />
<label for="terms">Accept terms</label>

<!-- Checked -->
<input type="checkbox" id="news" checked />
<label for="news">Subscribe</label>

<!-- Mixed (indeterminate) -->
<input type="checkbox" aria-checked="mixed" id="all" />
<label for="all">Select all</label>
NVDA Output
"Accept terms, checkbox, not checked
Subscribe, checkbox, checked
Select all, checkbox, half checked"
VoiceOver Output
"Accept terms, checkbox, unchecked
Subscribe, checkbox, checked
Select all, checkbox, mixed"
Narrator Output
"Accept terms, check box, unchecked
Subscribe, check box, checked
Select all, check box, partially selected"

Image with alt text

Images with alt text are announced as graphics (NVDA/JAWS) or images (VoiceOver/Narrator). Images without alt text are flagged as missing accessible names in audit reports.

HTML
<!-- With alt text -->
<img src="logo.png" alt="Speakable logo" />

<!-- Without alt text (accessibility issue) -->
<img src="hero.png" />
NVDA Output
"Speakable logo, graphic
graphic"
VoiceOver Output
"Speakable logo, image
image"
Narrator Output
"Speakable logo, image
image"

Expandable button

Buttons with aria-expanded announce their expanded/collapsed state. Useful for accordions, dropdowns, and disclosure widgets.

HTML
<button aria-expanded="false">Show details</button>

<!-- After clicking -->
<button aria-expanded="true">Show details</button>
NVDA Output
"Show details, button, collapsed
Show details, button, expanded"
VoiceOver Output
"Show details, button, collapsed
Show details, button, expanded"
Narrator Output
"Show details, button, collapsed
Show details, button, expanded"

Table structure

Tables are announced with their dimensions. Each screen reader formats table announcements differently.

HTML
<table>
  <tr>
    <th>Name</th>
    <th>Role</th>
  </tr>
  <tr>
    <td>Alice</td>
    <td>Engineer</td>
  </tr>
</table>
NVDA Output
"table
  row
    Name, column header
    Role, column header
  row
    Alice
    Engineer"
VoiceOver Output
"table, 2 rows, 2 columns
  row
    Name, column header
    Role, column header
  row
    Alice
    Engineer"
Narrator Output
"table, 2 rows, 2 columns
  row
    Name, column header
    Role, column header
  row
    Alice
    Engineer"

Semantic diff

Compare two HTML versions to detect accessibility changes. The diff shows added, removed, and changed nodes with property-level detail.

HTML
# Before (old.html)
<button>Save</button>

# After (new.html)
<button aria-label="Save document">Save</button>

# CLI command
speakable new.html --diff old.html
NVDA Output
# Diff output shows:
Changed: root.children[0]
  name: "Save" → "Save document"

Selector filtering

Use CSS selectors to narrow analysis to specific elements. Useful for component-level testing.

HTML
<!-- page.html contains many elements -->
<nav aria-label="Main">...</nav>
<main>
  <button>Submit</button>
  <button>Cancel</button>
</main>

# Analyze only buttons
speakable page.html --selector "button"
NVDA Output
"Submit, button
Cancel, button"
Narrator Output
"Submit, button
Cancel, button"

These examples show correct usage patterns. To see what goes wrong when markup is incorrect, check the Common Mistakes page which pairs bad patterns with their fixes. For details on how roles like navigation, button, and heading are resolved, see ARIA Roles. The Usage Guide covers how to reproduce these outputs locally with the CLI.

Related Pages

API Reference

Full programmatic API for parsing HTML and rendering screen reader output.

Common Mistakes

Real-world HTML patterns that break screen reader experiences and how to fix them.

Component Patterns

Accessible implementations of common UI widgets like tabs, modals, and menus.

Usage Guide

Practical walkthrough of CLI commands, output formats, and workflow integration.