Blog · 14 min read

7 Steps for Developers to Test and Fix Keyboard Accessibility

Developer testing website with keyboard

All website functionality must be operable via a keyboard alone, with no mouse, trackpad, or touch gesture required to complete any task. This single requirement sits behind four WCAG success criteria that web teams must satisfy: SC 2.1.1, 2.1.2, 2.4.3, and 2.4.7. The rest of this guide translates those criteria into failure patterns, a repeatable test script, and concrete fixes.

TL;DR:

  • Many keyboard accessibility issues stem from focus indicators being hidden or too low in contrast, focus order that does not follow visual flow, and elements that look interactive but are not focusable.
  • Native HTML elements like buttons and inputs should be used whenever possible to ensure automatic keyboard functionality and correct focus behavior.
  • Focus management during dynamic updates, such as opening or closing modals, is critical to prevent focus traps and ensure smooth navigation.
  • Custom widgets must follow ARIA roles and keyboard patterns to be accessible, with arrow keys, Enter, Space, and Esc used consistently for internal navigation and control.
  • Regular manual keyboard testing is essential after every change, as automated scans cannot fully verify real-world focus flow, trap issues, or complex component behaviors.
AccessWiser
accesswiser.com
Find Keyboard Barriers in Your Code
AccessWiser identifies accessibility issues against WCAG 2.2 AA criteria, links each finding to affected elements, and provides fixing guidance.
Explore AccessWiser

Table of Contents

1. Common keyboard accessibility problems to triage

Keyboard barriers tend to repeat across sites, which makes them easy to spot once you know the pattern. Most trace back to a handful of root causes.

  • Focus indicators that are missing, suppressed by CSS, or too low-contrast to see against the background.
  • Focus order that jumps around the page instead of following the visual and logical task flow.
  • Elements that look interactive but cannot receive focus, or elements that take focus without doing anything useful.
  • Positive tabindex values that override natural document order and produce an unpredictable tabbing sequence.
  • Keyboard traps inside modals, dropdown menus, date pickers, or embedded third-party widgets, where focus enters but never finds a way out.

Each of these problems blocks a different part of the experience, but they share a root cause: the interface was built and tested with a mouse in hand, and keyboard behavior was never checked.

2. Key WCAG success criteria and how they translate to keyboard behavior

Four criteria define what “keyboard accessible” actually means in code, and each one maps to a specific, testable behavior.

  • SC 2.1.1 (Keyboard): every control a mouse user can operate, a keyboard user must be able to operate too, with no exceptions for custom widgets.
  • SC 2.1.2 (No Keyboard Trap): once focus enters any component, the user must be able to move it away using only standard keys like Tab or Esc.
  • SC 2.4.3 (Focus Order): the sequence focus follows through the page must preserve meaning and support the task, not just follow raw DOM order by accident.
  • SC 2.4.7 (Focus Visible): wherever keyboard focus lands, there must be a visible indicator with enough contrast to be seen.

These four criteria, documented by Arizona State University’s accessibility team, form the backbone of nearly every keyboard accessibility audit.

3. How to test keyboard accessibility: checklist and step-by-step script

A reliable test takes a few minutes per page and needs nothing but a keyboard.

  1. Unplug your mouse or set it aside, then load the page fresh.
  2. Press Tab repeatedly and watch where focus goes: does it reach every link, button, and form field?
  3. Confirm a visible focus indicator appears at each stop, with no gaps where focus seems to vanish.
  4. Use Shift+Tab to move backward and check that the order is the reverse of forward tabbing.
  5. Activate buttons and links with Enter or Space and confirm they do what a mouse click would do.
  6. Open any modal, menu, or custom widget, then try arrow keys where relevant and Esc to close it.
  7. Verify that closing a dialog or menu returns focus to a sensible place, usually the control that opened it.

Ask yourself four questions as you go: can you reach every control, is focus always visible, does activation behave predictably, and is there any point where you get stuck? When a component involves announcements, labels, or live regions, add a screen reader pass with NVDA, JAWS, or VoiceOver, since keyboard behavior and screen reader compatibility are related but not identical checks. Automated scanners catch many code-level issues quickly, but manual keyboard testing remains essential for complex interactive components that scanners cannot operate on their own.

Pro Tip: Run the keyboard walkthrough before every release, not just during an annual audit; regressions creep in with nearly every redesign or new widget.

4. Implementation patterns: HTML, CSS, and JS fixes that make components keyboard-friendly

Most keyboard problems disappear when you start with native HTML. A <button>, <a>, or <input> comes with built-in keyboard support: focusability, Enter and Space activation, and correct behavior in forms. Reaching for a <div> with a click handler means rebuilding all of that by hand, and teams frequently miss a step.

  • Use native elements (button, a, input, select) wherever the design allows, since their keyboard behavior is automatic.
  • Limit tabindex to two values only: 0 to make a non-native element focusable in natural order, and -1 to let you move focus there with JavaScript; positive tabindex values break assistive technology compatibility and should never be used to reorder focus.
  • Style focus with :focus-visible so the indicator appears for keyboard users without showing on every mouse click, and make sure the indicator has enough size and contrast to be seen.
  • Add a skip-to-content link as the first focusable element on the page, paired with semantic landmarks and a correct heading structure, so keyboard users are not forced to tab through the entire navigation on every page load.
  • Manage focus during dynamic changes: when a dialog opens, move focus to a meaningful element inside it; when it closes, return focus to the control that triggered it; never remove an element that currently holds focus without redirecting focus somewhere sensible first.

Pro Tip: If you must reorder tab stops, change the actual DOM order instead of reaching for tabindex. The browser’s natural order is easier to maintain and easier for everyone to reason about.

5. Focus management, ARIA conventions, and custom widget keyboard interactions

Custom widgets like menus, tablists, trees, and grids need their own keyboard conventions, and the W3C’s ARIA Authoring Practices Guide documents them in detail. The core pattern repeats across most composite components: Tab moves focus into the widget as a whole, arrow keys move within it, and Tab moves focus back out to the next item on the page.

  • Reach for ARIA roles and APG keyboard patterns only when a native element cannot do the job.
  • Include just one stop in the page’s tab sequence for a composite widget, then handle internal movement with arrow keys, which keeps tab sequences short and predictable.
  • Use aria-hidden or the inert attribute to keep background content from receiving focus while a modal is open, and give every modal an Esc handler that closes it and returns focus to the trigger.
  • Avoid making static, non-interactive content focusable; if a rare case requires it, document the reason and confirm it does not disrupt the surrounding flow.

6. Diagnosing and fixing keyboard traps and other failures

Keyboard traps are among the most disruptive failures because they stop a user cold instead of just slowing them down.

  1. Reproduce the trap by tabbing into the suspect component and trying Tab, Shift+Tab, and Esc to escape it, logging exactly where focus gets stuck.
  2. Check whether a recent DOM change removed the focused element outright, which is a frequent cause of focus loss in single-page applications after a route change.
  3. Fix modals by setting focus on open and restoring it on close, rather than leaving focus wherever it happened to land.
  4. Fix menus and drag-and-drop interfaces by confirming every action has a keyboard equivalent and that Esc always provides an exit.
  5. Re-run the full keyboard walkthrough after each fix, and schedule a repeat check after any release that touches navigation, modals, or route handling, since regressions are common even on previously compliant pages.

7. Handling keyboard shortcuts and avoiding conflicts

Custom keyboard shortcuts can speed up power users, but they also carry real risk of breaking the experience for everyone else. A shortcut that overrides a browser or screen reader command, such as using a bare letter key to trigger an action, can silently disable functionality that assistive technology users depend on every day.

Keep single-character shortcuts off by default, or let users remap or turn them off entirely. When a shortcut is necessary, pair it with a modifier key combination that is unlikely to collide with browser or screen reader shortcuts, and document the full list of shortcuts somewhere discoverable, such as a help panel reachable by keyboard. Never assign a shortcut to a key that duplicates a core browser function like Ctrl+F or Ctrl+W, and test every custom shortcut with a screen reader active, since some assistive technologies intercept certain keys before your JavaScript ever sees them.

If your application already ships global shortcuts, audit them against common screen reader commands and against each other, since conflicting shortcuts across components are just as disruptive as conflicts with the browser. A consistent, well-documented shortcut scheme respects the keyboard users who rely on it most while staying out of the way of everyone else.

8. Guidelines for designing keyboard-accessible forms

Forms are where keyboard accessibility failures cause the most direct harm, since a broken form blocks a task outright: a purchase, an application, a sign-up.

Every field needs a programmatically associated label, reachable by keyboard and announced by assistive technology, not just placeholder text that disappears on input. Group related fields, such as a set of radio buttons, with fieldset and legend so their relationship is clear without visual cues. Error messages need to be announced and linked to their field with aria-describedby, and focus should move to the first invalid field after a failed submission instead of leaving the user stranded at the bottom of the form.

Accessible form error and focus flow

Custom form widgets, like a styled dropdown or a date picker, need the same keyboard support a native <select> or <input type="date"> would provide automatically, which is one more reason to reach for native elements whenever the design permits it. Multi-step forms should preserve a logical tab order between steps and announce progress clearly, since a form that works visually but loses keyboard users at step two has failed the people who need it most.

9. Supporting keyboard accessibility in custom widgets and controls

Custom widgets, carousels, accordions, autocomplete fields, tooltips, and the like, carry the highest risk of keyboard failure because they have no built-in browser behavior to fall back on. Every interaction you add visually needs a matching keyboard interaction built in deliberately.

An accordion needs Enter or Space to expand and collapse each panel, with focus staying on the trigger so the user can keep moving through the list. An autocomplete field needs arrow keys to move through suggestions and Enter to select one, with Esc closing the suggestion list without submitting the form. A carousel needs a way to pause autoplay and move between slides without requiring precise timing, since a sighted mouse user can act faster than a keyboard interaction often allows.

The safest approach for any custom control is to build it against a documented pattern rather than improvising, since the W3C’s APG keyboard interface guidance lays out conventions for the widgets developers build most often. Matching those conventions means assistive technology users encounter the same behavior they already expect from similar controls elsewhere on the web.

A keyboard user with no skip link has to tab through every navigation item, every logo link, and every banner element before reaching the content they came for, on every single page. A skip link fixes this directly: it is the first focusable element on the page, visually hidden until focused, and it jumps focus straight to the main content area when activated.

Landmarks reinforce the same goal at a structural level. Marking the page with header, nav, main, and footer elements, or their ARIA landmark equivalents, gives both keyboard and screen reader users a map of the page they can jump through instead of tabbing linearly from the top. A correct heading structure, with one h1 and nested headings that follow a logical order, serves the same purpose for anyone navigating by heading rather than by tab stop.

Skip link and landmark navigation paths

Together, skip links and landmarks turn a long, flat tab sequence into a page with clear entry points, cutting the effort needed to reach the content that matters.

11. AccessWiser perspective: pairing automated scans with manual keyboard testing

Automated scans catch a meaningful share of code-level keyboard issues fast, but they cannot operate a modal or judge whether a focus order actually makes sense, which is why manual keyboard testing stays essential even on a well-scanned site. AccessWiser’s own scans map findings to WCAG, Section 508, and EN 301 549, pairing each one with plain-language fix guidance, scheduled re-checks, and a visitor-facing widget that gives people more control over how they view a page.

— The AccessWiser Team

12. Put keyboard accessibility to the test on your own site

Fixing keyboard barriers starts with knowing exactly where they live in your code, down to the specific element and the criterion it fails. An AccessWiser scan delivers that detail directly: code-level findings, plain-language steps to fix each one in your own codebase, and dated records you can point to as documentation of the work. Scheduled re-checks then catch regressions after your next release, since a form or modal that passes today can break again after the smallest update.

None of this replaces the manual keyboard walkthrough described above. Automation and manual testing work best together, one surfacing issues at scale and the other confirming the experience actually works for a real person using only a keyboard. If your team is ready to see where your own site stands, the AccessWiser pricing page lists the Starter, Basic, Pro, and Business plans, along with options for extra page and site scans, so you can start with a scan sized to your site.

Sources

For primary guidance beyond this article, the W3C’s ARIA Authoring Practices Guide documents keyboard conventions for custom widgets, while the WCAG Understanding page on focus order explains the reasoning behind SC 2.4.3. For legal context, note that the DOJ has set staggered WCAG 2.1 AA compliance deadlines of April 26, 2027 and April 26, 2028 for state and local government entities, a timeline explained further by this plain-language ADA compliance summary. Testing guidance and legal obligations are related but distinct: one tells you how to check your work, the other tells you why the work is required.

FAQ

How do I turn on the accessibility keyboard?

This usually refers to your operating system’s built-in on-screen keyboard or keyboard-related accessibility settings, found in Settings under Accessibility on most platforms. It is separate from website keyboard accessibility, which is a property of how a site is built, not a setting a visitor turns on.

Is WCAG legally required?

WCAG’s legal status depends on the organization and jurisdiction: in the United States, the DOJ requires WCAG 2.1 Level AA for state and local government websites, with deadlines of April 26, 2027 for larger entities and April 26, 2028 for smaller ones. Private businesses face accessibility obligations under other laws that frequently reference WCAG as the practical standard, so treating it as a baseline is the safer approach regardless of entity type.

What is keyboard accessibility?

Keyboard accessibility means every piece of website functionality can be operated using only a keyboard, with no mouse, trackpad, or touch input required. It is governed primarily by WCAG success criteria 2.1.1, 2.1.2, 2.4.3, and 2.4.7, covering operability, escaping traps, focus order, and focus visibility.

How do I turn off the accessibility keyboard?

If an on-screen or accessibility keyboard appeared on your device, it can typically be disabled from the same Accessibility settings menu used to turn it on. This setting lives at the operating system level and has no effect on whether a website itself supports keyboard navigation.

What does AccessWiser check for keyboard accessibility?

AccessWiser scans map code-level findings to WCAG AA, with Section 508 and EN 301 549 references, and pair each finding with plain-language fix guidance along with scheduled re-checks to catch regressions. Pricing starts at 24 USD per month on the Starter plan, with Basic, Pro, and Business tiers available for teams that need more scans or pages covered.

Articles on this blog are general information about web accessibility, not legal advice. Laws change and their application depends on your specific situation — for decisions with legal consequences, consult a qualified legal professional.

Articles on this blog are general information about web accessibility, not legal advice. Laws change and their application depends on your specific situation — for decisions with legal consequences, consult a qualified legal professional.