Keyboard accessibility: how to test and fix your site

Who relies on a keyboard to use websites?

More people than you might think. Keyboard access matters for:

• Blind people and many people with low vision, who move through pages with a screen reader and the keyboard.
• People with motor disabilities, such as tremors, arthritis or paralysis, who find a mouse hard or impossible to use.
• People who use switches, mouth sticks, head pointers or other tools that act like a keyboard.
• People who use speech recognition, which works best when every control is a real, focusable element.
• Anyone with a broken wrist, a dead trackpad or a love of keyboard shortcuts.

WCAG makes keyboard access a Level A requirement: success criterion 2.1.1 says all functionality must work through a keyboard. Many assistive tools act like a keyboard, so they benefit too.

How do you test a website with only a keyboard?

Click in the browser's address bar, then put your mouse aside. Use these keys:

As you go, ask yourself:

• Can I always see where the focus is?
• Does focus move in the order I'd read the page?
• Can I reach and use every menu, button, form field and video control?
• Can I open and close menus, dialogs and cookie banners?
• Did focus ever get stuck, vanish or jump somewhere unexpected?

On a Mac, Safari skips links when you press Tab until you turn on "Press Tab to highlight each item on a webpage" in Safari's Advanced settings. Turn it on before you test.

How do you make keyboard focus visible?

The focus indicator, usually an outline, shows keyboard users where they are. Without it, using a site by keyboard is like using a mouse with an invisible pointer. WCAG 2.4.7 Focus Visible (Level AA) requires it.

• Never remove the outline with outline: none unless you add a clear focus style in its place.
• Use the CSS :focus-visible selector to show a strong focus style to keyboard users without changing how mouse clicks look.
• Make your focus style stand out: at least 3:1 contrast against the colors around it, and thick enough to notice.

WCAG 2.2 added a related rule. Focus Not Obscured (Minimum), success criterion 2.4.11 at Level AA, says the focused item must not be entirely hidden by content you added, such as a sticky header, a cookie banner or a chat window. The AAA version, 2.4.12, says no part of it should be hidden. A common fix is the CSS scroll-padding property, which stops the page from scrolling focused items under a sticky header.

What makes a good focus order?

Focus should move through the page in an order that keeps its meaning, usually the same order you'd read it (WCAG 2.4.3, Level A). The browser follows the order of your HTML, so the easiest way to get this right is to make the code order match the visual order.

• Don't use tabindex values of 1 or more. They override the natural order and are hard to maintain. tabindex="0" (add to the order) and tabindex="-1" (focus only by script) are fine.
• Watch out for CSS that reorders content, like flexbox order or grid placement. The page looks right, but focus jumps.
• When a dialog opens, move focus into it. When it closes, send focus back to the button that opened it.
• Hidden content, such as a closed mobile menu, should not take focus. Hide it fully, for example with display: none or the inert attribute.

What are skip links and keyboard traps?

A skip link is a link at the very top of the page that says "Skip to main content". It lets keyboard users jump past the header and menu instead of tabbing through them on every page. It can stay hidden until it gets focus, as long as it appears on screen when it does. WCAG 2.4.1 Bypass Blocks (Level A) asks for a way to skip repeated content, and skip links, landmarks and headings all help.

A keyboard trap is a spot where focus gets in and can't get out. WCAG 2.1.2 No Keyboard Trap (Level A) rules it out. Traps often hide in embedded video players, maps, chat windows, rich text editors and third-party forms. A modal dialog may keep focus inside on purpose, but it must close with Escape or a close button.

How do you make custom controls work with a keyboard?

The simplest fix is to use real HTML elements. Buttons, links with an href, inputs and selects all work with the keyboard and screen readers out of the box. A div or span with a click handler does not: it can't get focus and doesn't respond to Enter or Space.

• Use a button for actions and a link for going to another page.
• Use the details and summary elements for simple show and hide sections.
• If you must build a custom control, give it a role, tabindex="0", key handling for Enter and Space, and states such as aria-expanded.
• For menus, tabs, sliders and comboboxes, follow the keyboard patterns in the W3C's ARIA Authoring Practices Guide.
• Make anything that opens on hover also open on focus or with Enter.
• Give drag and drop a keyboard alternative, such as "Move up" and "Move down" buttons.

Test third-party chat widgets, cookie banners and payment forms the same way as your own code.

Can an accessibility widget fix keyboard problems?

No. Keyboard problems live in your site's code, and a widget can't turn a div into a working button or release a keyboard trap. Fixing the code is the only real fix.

Octo Assist can make keyboard use easier on a site that already works. Visitors can press Alt+Shift+A to open its panel, turn on a bold Focus outline, and use Keyboard shortcuts to jump between headings, links, buttons, form fields and images with single keys.