# Tell screen readers when the content changes (Web HIG tip #18)

Someone filters orders on [example.com/orders](http://example.com/orders). The list updates in place: three shipped rows appear, and a heading now says "3 shipped orders." A screen reader user is still on the Status control and hears nothing, so they don't know the page changed. The results are visible. They were never announced.

**Web HIG tip #18 (Quick #78):** Dynamic content updates must be announced to screen readers (`aria-live` or focus management).

## Why it matters

An in-page update does not load a new document, so the screen reader does not announce a new page. Without a live-region update or a focus move:

- People using a screen reader can miss a filter, save, or cart change that happened elsewhere on the page
- Keyboard users can be left on the control they just used, with no cue that content below or beside it changed
- A visual toast or a badge is easy to miss if it is not also announced, or if focus never moves to it
- Announcing every keystroke while someone types a query can be just as unusable as announcing nothing

[Quick #78](https://github.com/frozonfreak/webhig/blob/bcd6cf696f688acd77ed5018036aebd9927bcddc/HIG-QUICK.md) is Quick-only guidance (no rule ID of its own). The HIG does not add a longer normative technique for this item. [§8.3](https://github.com/frozonfreak/webhig/blob/bcd6cf696f688acd77ed5018036aebd9927bcddc/HIG.md#83-audit-outcomes-informative) notes that assistive-technology announcements stay manual: a passing automated check is not evidence that a screen reader spoke.

## Before and after

This in-page filter redraws the list and leaves the announcement to chance. JavaScript stops the navigation, so this is a same-document update, not a new page:

```html
<form id="order-filter" action="https://example.com/orders" method="get">
  <label for="status">Status</label>
  <select id="status" name="status">
    <option value="shipped">Shipped</option>
  </select>
  <button type="submit">Filter</button>
</form>
<div id="results">
  <h2 id="results-heading">Orders</h2>
  <ul>
    <li>Order 1042 — shipped to name@example.com</li>
  </ul>
</div>
<script>
  const form = document.getElementById('order-filter');
  const heading = document.getElementById('results-heading');
  form.addEventListener('submit', (event) => {
    event.preventDefault();
    // Fetch and render omitted: the heading and list update in place,
    // with no live region and no focus move.
    heading.textContent = '3 shipped orders';
  });
</script>
```

Keep a live region in the document before the update, then change its text when the results change. This is a same-document illustration, not a complete orders app. It does not cover a full navigation: a new document is usually announced as a new page.

```html
<form id="order-filter" action="https://example.com/orders" method="get">
  <label for="status">Status</label>
  <select id="status" name="status">
    <option value="shipped">Shipped</option>
  </select>
  <button type="submit">Filter</button>
</form>
<p id="results-status" role="status"></p>
<div id="results">
  <h2 id="results-heading">Orders</h2>
  <ul>
    <li>Order 1042 — shipped to name@example.com</li>
  </ul>
</div>
<script>
  const form = document.getElementById('order-filter');
  const status = document.getElementById('results-status');
  const heading = document.getElementById('results-heading');
  form.addEventListener('submit', (event) => {
    event.preventDefault();
    // Fetch and render omitted: imagine the list now has three shipped orders.
    heading.textContent = '3 shipped orders';
    status.textContent = '3 shipped orders.';
  });
</script>
```

`role="status"` is a polite live region (it also implies `aria-atomic="true"`, so the whole message is read). Updating its text is not a promise that a given screen reader will speak, or when it will speak. If the update is a new view rather than a short status, moving focus to `results-heading` can be the clearer path — that is the "or focus management" half of Quick #78. A heading is not focusable by default: add `tabindex="-1"` so it can receive focus without joining the tab order. Do not combine a verbose live message and a focus move for the same change without checking that the pair is not noisy. This snippet does not implement fetching, errors, empty results, or a framework lifecycle. Setting the same status text again may not be announced; some implementations clear the region, then set the new text.

## Do this instead

- Put the live region in the HTML (or create it once on startup) before you change its text. An empty `role="status"` is a usual starting point
- Prefer a short, polite status for routine updates ("3 shipped orders."). Reserve assertive alerts for urgent messages; they can interrupt
- Keep the same information visible on the page. Don't announce a result that nobody can see
- Don't announce on every keystroke in a filter box; wait until the results actually change
- Don't put `aria-live` on a large, frequently changing block such as the whole results list; announce a short status instead
- If the update replaces the main view, move focus to a sensible heading or container. Give a non-interactive target `tabindex="-1"` so it can take focus without joining the tab order. A heading's name usually comes from its text; a generic container needs an accessible name
- Reuse one status region for successive updates rather than stacking new live regions

## Quick check for your app

On a test copy of [example.com/orders](http://example.com/orders), run an in-page filter or save with a screen reader your audience uses, and with the keyboard alone. Confirm that the change is announced, or that focus moved to the new content, and that typing a query does not flood announcements. Suitable automated checks can flag a missing live region or a missing focus target; they cannot confirm that assistive technology spoke. Pair them with a manual check on the browsers and screen readers you support. A green suite is evidence for what it actually exercised, not proof that every update is announced.

---

The Web HIG is an open set of guidelines for how the web should behave, not a component library. Design systems define how it looks. The Web HIG defines how it behaves.

- GitHub: <https://github.com/frozonfreak/webhig/discussions/36>
- Hashnode: <https://thewebhig.hashnode.dev/announce-dynamic-updates-web-hig-tip-18>
- Dev.to: <https://dev.to/frozonfreak/tell-screen-readers-when-the-content-changes-web-hig-tip-18-3c84>
- Bluesky: <https://bsky.app/profile/sastha.bsky.social/post/3n2fwblpm4c2e>
