Fixing Keyboard Navigation

What the keyboard rules in WCAG ask for

Keyboard access is not one rule but a small family of them. Most are at level A, the most basic level of WCAG 2.2, which means a failure here is treated as a barrier rather than an inconvenience. The Accessibility Checker reports the ones it can detect in code, and the rest need a quick manual test.

Visible focus styles have their own guide: fixing focus indicators. This page concentrates on whether focus can get somewhere, what happens when it arrives, and whether it can leave.

Why sites fail with the keyboard

Browsers give you keyboard support for free when you use the right HTML. A <button> is focusable and responds to Enter and Space. A link with an href is focusable and responds to Enter. Form fields, <select>, <details> and <summary> all work without a line of script. Keyboard failures nearly always come from replacing those elements with something that only listens for clicks.

• Clickable boxes. A <div> or <span> with a click listener is invisible to the Tab key and ignores Enter.
• Links with no destination. An <a> with no href is not focusable at all, and href="#" used as a button jumps to the top of the page when scripts fail.
• Hover-only menus. Submenus that appear on :hover never appear for someone tabbing through the header.
• Hand-built dialogs. A pop-up that is only a positioned box lets focus wander behind it, or grabs focus and never lets go.
• Positive tabindex values. A tabindex of 1 or more drags an element to the front of the queue and scrambles the order for everything else.
• Hidden but focusable content. Off-canvas menus, collapsed panels and slides moved off-screen with transform or opacity still take focus, so the outline vanishes into empty space.
• Third-party widgets. Chat launchers, review carousels, booking iframes and cookie banners are often written with little keyboard testing.

How to test a page with the keyboard

An automated scan can spot a clickable <div> or a positive tabindex, but it cannot press keys and see what happens. The manual test takes about ten minutes per template and finds far more.

Mac users: switch Tab on first

On a Mac, Safari does not move to links with Tab out of the box. Turn on Press Tab to highlight each item on a webpage in Safari's Advanced settings, or hold Option while pressing Tab. Firefox and Chrome on macOS follow the system-wide Keyboard navigation switch in System Settings under Keyboard. If you skip this, you will think the whole site is broken when it is not.

Spotting hidden focus

When the outline disappears, open the browser console and run document.activeElement after each Tab. It returns the element that currently has focus, which quickly exposes a hidden mobile menu link or an off-screen slide. In Chrome you can also add a live expression for document.activeElement so it updates as you tab.

The fix, step by step

Code patterns that work

A button that looks like anything

Designers often avoid <button> because of the default grey box. Strip the defaults once and it can look like text, an icon or a card.

<button type="button" class="plain-btn" aria-expanded="false" aria-controls="filters">
  Filter results
</button>

.plain-btn {
  background: none;
  border: 0;
  padding: 0;
  font: inherit;
  color: inherit;
  cursor: pointer;
}

A disclosure menu

<nav aria-label="Main">
  <ul>
    <li>
      <a href="/services/">Services</a>
      <button type="button" class="sub-toggle" aria-expanded="false" aria-controls="sub-services">
        <span class="visually-hidden">Show Services submenu</span>
      </button>
      <ul id="sub-services" hidden>
        <li><a href="/services/boilers/">Boiler servicing</a></li>
        <li><a href="/services/repairs/">Emergency repairs</a></li>
      </ul>
    </li>
  </ul>
</nav>

document.querySelectorAll('.sub-toggle').forEach(function (btn) {
  var panel = document.getElementById(btn.getAttribute('aria-controls'));
  btn.addEventListener('click', function () {
    var open = btn.getAttribute('aria-expanded') === 'true';
    btn.setAttribute('aria-expanded', String(!open));
    panel.hidden = open;
  });
  btn.parentElement.addEventListener('keydown', function (e) {
    if (e.key === 'Escape' && !panel.hidden) {
      panel.hidden = true;
      btn.setAttribute('aria-expanded', 'false');
      btn.focus();
    }
  });
});

Using the hidden attribute (or display: none) matters: it removes the closed submenu links from the tab order, whereas hiding them with opacity or a negative position leaves them focusable. The button needs an accessible name; see fixing ARIA labels for the options.

A modal dialog

<button type="button" id="open-quote">Get a quote</button>

<dialog id="quote" aria-labelledby="quote-title">
  <h2 id="quote-title">Request a quote</h2>
  <form method="dialog">
    <!-- fields -->
    <button value="send">Send</button>
    <button value="cancel" formnovalidate>Cancel</button>
  </form>
</dialog>

var opener = document.getElementById('open-quote');
var dlg = document.getElementById('quote');
opener.addEventListener('click', function () { dlg.showModal(); });
dlg.addEventListener('close', function () { opener.focus(); });

Current browsers generally restore focus to the opener themselves when a modal dialog closes, but the explicit opener.focus() costs nothing and covers older versions and dialogs closed by script.

A skip link

<a class="skip-link" href="#main">Skip to main content</a>
...
<main id="main" tabindex="-1">

.skip-link { position: absolute; left: -9999px; top: 0; }
.skip-link:focus { left: 1rem; top: 1rem; z-index: 1000;
  background: #111; color: #fff; padding: .75rem 1rem; }

The tabindex="-1" on <main> makes older browsers move the keyboard starting point along with the scroll position. It does not add <main> to the Tab sequence.

Composite widgets: tabs, sliders, carousels and grids

Some controls are groups rather than single buttons. The convention, set out in the W3C ARIA Authoring Practices Guide, is that Tab moves into the group once and out again, and the arrow keys move inside it. That keeps a set of twelve tabs or a date picker from costing twenty Tab presses.

• Tabs. Only the selected tab has tabindex="0"; the others have -1. Left and Right move between tabs, and Tab goes straight to the open panel. This technique is called a roving tabindex.
• Radio groups. Native radio buttons with the same name already behave this way. Do not rebuild them.
• Sliders and range inputs. A native <input type="range"> responds to the arrow keys. A custom slider needs the same, plus Page Up, Page Down, Home and End if it covers a wide range. WCAG 2.2 also asks that dragging is never the only way to set a value.
• Carousels. Provide visible previous, next and pause buttons that are real buttons. Slides not on screen should be hidden from focus, and auto-rotation should stop when anything inside the carousel has focus.
• Scrollable areas. A box with its own scroll bar, such as a wide price table, cannot be scrolled with the keyboard unless it or something inside it can take focus. Recent Chrome versions make such areas focusable automatically, but other browsers may not, so add tabindex="0", role="region" and a short aria-label to the scrolling wrapper.

Where the fixes live on common platforms

The code changes above are the same everywhere, but where you make them differs.

• WordPress. Menu and header markup comes from the theme, and pop-ups, sliders and forms come from plugins. Block themes get a skip link added automatically by WordPress core. See accessibility in WordPress for how to trace a fault to the theme or a plugin.
• Shopify. The header, mega menu, cart drawer and quick-view pop-ups live in theme sections and snippets written in Liquid, while review, upsell and chat widgets are injected by apps. Accessibility in Shopify covers editing those safely.
• React and Next.js. Keyboard problems usually come from click handlers on divs in components and from focus not being moved after client-side navigation. Accessibility in React and Next.js covers lint rules and focus management.
• Static and hand-built sites. Fix the shared header and footer include once, and every page benefits.

Edge cases and questions of judgement

Text editors that use Tab

A rich text editor or code box may reasonably use Tab to indent. That is allowed under 2.1.2 as long as there is a way out that the page explains, for example a note saying that Ctrl+M switches the Tab key back to moving focus, or that Escape leaves the editor.

Focus on page load

Do not autofocus a search box or newsletter field on every page. It skips screen reader users past the page heading and can make mobile keyboards pop up unexpectedly. Autofocus is reasonable on a page whose only purpose is that field, such as a dedicated search page or a login screen.

Things that happen on focus

A select list that navigates to a new page as soon as the value changes is a trap for keyboard users, because pressing the down arrow to read the options fires the change. Add a Go button instead. The same applies to fields that submit the form when they receive focus.

Single-key shortcuts

If your site or web app uses single letters as shortcuts, such as J and K to move between items, speech recognition users can trigger them by accident when dictating. Offer a setting to turn them off or require a modifier key such as Ctrl.

Sticky headers and cookie banners

When a focused link slides under a fixed header or a cookie banner, WCAG 2.2 criterion 2.4.11 is failed. Adding scroll-padding-top to the html element equal to the header height usually solves the header case; banners should be dismissible and should not cover focused content while open.

Keeping it fixed

1. Add a lint rule to the build that flags click listeners on non-interactive elements and positive tabindex values.
2. Put a keyboard-only walk-through of the main journeys into your release checklist, especially after a theme update or a new plugin or app.
3. Ask suppliers of widgets and apps whether their product has been tested with a keyboard and a screen reader before you install it.
4. Run the Accessibility Audit on each template after changes and compare with the previous report.
5. Keep a small library of known-good patterns, such as the button reset, disclosure menu, dialog and skip link above, and reuse them instead of rebuilding.