Accessible JavaScript

1. The problem: a click handler on a div

A food-delivery app has an "Add to basket" box made from a <div> with a click handler. A mouse user taps it and gets food. A keyboard user presses Tab and never lands on it. A screen reader user hears plain text, not a button. They go hungry.

A click handler is a function that runs when something is clicked. On a real <button>, the browser also runs it for Enter and Space. On a <div>, it runs only for the mouse.

The middle option is a trap. tabindex="0" makes the div focusable, but Enter still does nothing. You would have to add a role, two key handlers and a focus style. The button already has all of it.

2. Keyboard events: handle the right keys, and only those

A keyboard event (keydown) tells your script which key was pressed. Use it to add keys people expect. Do not use it to steal keys that the browser or a screen reader already uses.

A composite widget is one control made of several parts, like a set of tabs. Widget roles shows the full key patterns. In browse mode, most screen readers catch arrows and letters before your page even sees them. That is normal.

// Close a pop-up with Escape and give focus back
popup.addEventListener("keydown", function (event) {
  if (event.key === "Escape") {
    popup.hidden = true;
    openButton.setAttribute("aria-expanded", "false");
    openButton.focus();
  }
});

3. Managing focus after the page changes

Focus is the spot where the keyboard is "pointing". If script deletes the focused element, focus has nowhere to stand. The browser usually drops it onto <body>, the whole page. A screen reader may go silent or jump to the top.

The fix is one line: after removing an item, call .focus() on something sensible. Usually that is the next item, or the previous one if it was last.

function removeItem(li) {
  var next = li.nextElementSibling || li.previousElementSibling;
  li.remove();
  if (next) next.querySelector("button").focus();
  else emptyMessage.focus();   // has tabindex="-1"
}

The same rule applies when you open something. When a panel or dialog opens, move focus into it. When it closes, send focus back to the button that opened it (see Managing focus).

4. Announcing results that arrive later

Some answers take time: a search, a save, a payment. Sighted users see "Searching…" then "3 results". A screen reader user hears nothing, unless you use a live region.

A live region is an element the screen reader watches. When its text changes, the new text is read out. role="status" is a polite live region: it waits until the user stops typing or reading.

For an error that needs action now, role="alert" is stronger: it interrupts. Use it rarely. For most updates, role="status" is right (see Live regions).

5. Keep state attributes in sync

A disclosure is a button that shows or hides a panel. Its aria-expanded attribute tells screen readers if the panel is open. The browser does not update it for you. If your script shows the panel but forgets the attribute, the screen reader says "collapsed" while it is open.

The same goes for aria-pressed on toggle buttons, aria-selected on tabs, and aria-current on the current page link (see States and widget properties). A good habit: write one function that sets the look and the attribute together.

6. Respect reduced motion in script too

Some people get dizzy or sick from movement on screen. They can switch on "reduce motion" in their device settings. CSS can read this with @media (prefers-reduced-motion: reduce). JavaScript animations need to check it too.

var calm = window.matchMedia("(prefers-reduced-motion: reduce)");
function addToBasket() {
  if (calm.matches) { showBadgeInstantly(); }
  else { flyBadgeToBasket(); }
}
// The setting can change while the page is open:
calm.addEventListener("change", updateAnimations);

7. Do not trap focus, and work before script loads

A keyboard trap is a spot that Tab can enter but not leave. WCAG 2.1.2 forbids it. Scripts cause traps by accident: a handler that cancels Tab, or one that pulls focus back on blur.

input.addEventListener("keydown", function (e) {
  if (e.key === "Tab" && !isValid()) {
    e.preventDefault(); // user is stuck
  }
});

input.addEventListener("blur", function () {
  if (!isValid()) showErrorText();
  // focus moves on as normal
});

A modal dialog may keep focus inside on purpose, but only with a way out, like Escape. <dialog> opened with showModal() does this for you.

Progressive enhancement means building the plain HTML version first, then adding script on top. If the script fails or loads slowly, the page still works.

<span onclick="openMenu()">Menu</span>
<div onclick="search()">Search</div>

<a href="/menu">Menu</a>
<form action="/search" method="get">
  <label for="q">Search</label>
  <input id="q" name="q" type="search">
  <button>Search</button>
</form>

Common mistakes