SiteLint documentation and guidelines

Verify character key shortcuts

The full HTML output:

Description

This rule does not automatically validate anything. It simply reminds you to manually verify that if a web application implements single-character keyboard shortcuts – those using only letters, numbers, punctuation, or symbol characters (e.g., a, 1, or symbols) – at least one of the following mechanisms is provided: the shortcut can be turned off, it can be remapped to include one or more non-printable modifier keys such as Ctrl or Alt, or the shortcut is only active when the component that uses it has focus.

Character key shortcuts can interfere with speech input users, people using alternative keyboards, and individuals who accidentally trigger keys due to tremors or limited dexterity. This requirement comes from WCAG Success Criterion 2.1.4 (Character Key Shortcuts) at Level A. Because this rule relies entirely on human judgment, you must inspect all interactive components and global keyboard handlers to confirm compliance.

Disabilities impacted

  • Motor impairments – Users with limited dexterity, tremors, or who use alternative input devices (e.g., switches, mouth sticks, head wands) may unintentionally trigger single-character shortcuts while typing or navigating, causing unexpected actions and loss of control.
  • Cognitive disabilities – Unexpected behavior triggered by accidental key presses can disorient users with attention deficits, memory impairments, or learning disabilities, making it harder to complete tasks and increasing cognitive load.
  • Speech input users – People who rely on speech recognition software (e.g., Dragon NaturallySpeaking) to control their computer dictate commands that are translated into keystrokes. Single-character shortcuts are frequently triggered by spoken words that contain those letters, interfering with normal speech input.
  • Visual impairments – Screen reader and screen magnifier users who navigate by keyboard may inadvertently activate shortcuts they cannot see or anticipate, particularly when focus unexpectedly shifts or content changes without announcement.

Why it matters

Single-character keyboard shortcuts can create significant barriers for people who rely on assistive technologies. ADA and WCAG compliance requires that web content be operable through multiple input methods. When a web application assigns functionality to individual character keys without providing a way to disable or remap them, it effectively blocks speech input users from using their primary navigation method. Section 508 and the European Accessibility Act (EAA) both mandate operable interfaces, and unguarded character shortcuts are among the most common violations found in web applications like rich text editors, code editors, and custom player controls.

Beyond legal compliance, providing remappable or focus-scoped shortcuts is a hallmark of inclusive design. It gives users agency over their interaction model and prevents the frustration caused by accidental activation. For enterprise applications and government services, failing this criterion can result in formal complaints, litigation risk, and exclusion of employees and citizens who depend on speech input or adapted keyboards.

Coding problems and solutions

Common pitfalls to manually verify

Since this rule performs no automated analysis, use the following checklist when auditing a page:

  • Global single-character key listeners – Check whether keydown, keyup, or keypress event listeners attached to document or window respond to unmodified letter or number keys (e.g., pressing s to open search).
  • Rich text editors and code editors – Editors often bind single keys for formatting (b for bold, i for italic) without requiring Ctrl. Verify these are either remappable or only active when the editor has focus.
  • Custom media players – Video and audio players frequently use single keys like m (mute), f (fullscreen), or arrow keys for seeking. Confirm players respect focus scope or offer a preferences panel.
  • Game and interactive canvas elements – WebGL games and canvas-based applications commonly bind letter keys (w, a, s, d) for character movement. Ensure a settings menu allows rebinding or disabling keys.
  • Third-party widgets and embeds – Chat widgets, helpdesk overlays, and embedded third-party components may register global shortcuts. Use browser DevTools to inspect all event listeners on document and window.
  • Keyboard shortcuts without visible documentation – Even if shortcuts are documented in a hidden help page, verify they appear in a visible, accessible location and can be changed by the user.

How to fix it

1. Require modifier keys

The simplest approach is to require at least one modifier key (Ctrl, Alt, Meta, or Shift) for all keyboard shortcuts. This avoids the SC 2.1.4 requirement entirely because single non-modifier character keys are not used.

Correct example
<button aria-keyshortcuts="Ctrl+S">Save</button>

<script>
document.addEventListener('keydown', (event) => {
  if (event.ctrlKey && event.key === 's') {
    event.preventDefault();
    saveDocument();
  }
});
</script>
Incorrect example
<script>
document.addEventListener('keydown', (event) => {
  if (event.key === 's') {
    event.preventDefault();
    saveDocument();
  }
});
</script>

2. Scope shortcuts to focused components

Bind shortcuts only to the specific element that needs them. When the shortcut is only active while the relevant component has focus, it satisfies the third condition of SC 2.1.4.

Correct example
<div id="rich-editor" contenteditable="true" role="textbox" aria-multiline="true">
  Start typing...
</div>

<script>
const editor = document.getElementById('rich-editor');

editor.addEventListener('keydown', (event) => {
  if (event.key === 'b') {
    event.preventDefault();
    document.execCommand('bold');
  }
});
</script>
Incorrect example
<div id="rich-editor" contenteditable="true" role="textbox" aria-multiline="true">
  Start typing...
</div>

<script>
document.addEventListener('keydown', (event) => {
  if (event.key === 'b') {
    event.preventDefault();
    document.execCommand('bold');
  }
});
</script>

3. Provide a mechanism to turn off shortcuts

Add a user preference setting (e.g., a toggle in a settings panel) that disables all single-character keyboard shortcuts. Persist the preference using localStorage or a user account setting.

Correct example
<label>
  <input type="checkbox" id="toggle-shortcuts" checked>
  Enable single-key shortcuts
</label>

<script>
const toggle = document.getElementById('toggle-shortcuts');

function handleKeyDown(event) {
  if (event.ctrlKey || event.altKey || event.metaKey) {
    return;
  }

  const shortcutsEnabled = localStorage.getItem('charShortcuts') !== 'false';

  if (!shortcutsEnabled) {
    return;
  }

  if (event.key === 's') {
    event.preventDefault();
    toggleSearch();
  }
}

toggle.addEventListener('change', () => {
  localStorage.setItem('charShortcuts', toggle.checked);
});

const saved = localStorage.getItem('charShortcuts');

if (saved !== null) {
  toggle.checked = saved === 'true';
}

document.addEventListener('keydown', handleKeyDown);
</script>
Incorrect example
<script>
document.addEventListener('keydown', (event) => {
  if (event.key === 'h') {
    openHelp();
  }
});
</script>

4. Provide a mechanism to remap shortcuts

Allow users to reassign single-character shortcuts to include modifier keys or to different keys altogether. Show the current mapping in an accessible settings interface and save user preferences.

Correct example
<section aria-labelledby="shortcuts-heading">
  <h2 id="shortcuts-heading">Keyboard Shortcuts</h2>
  <ul role="list">
    <li>
      <label for="shortcut-search">Search</label>
      <input id="shortcut-search" type="text" value="s" data-action="search">
    </li>
    <li>
      <label for="shortcut-help">Help</label>
      <input id="shortcut-help" type="text" value="h" data-action="help">
    </li>
  </ul>
</section>

<script>
const shortcuts = {
  help: 'h',
  search: 's'
};

const customShortcuts = JSON.parse(
  localStorage.getItem('customShortcuts') || '{}'
);

// Note: Object.assign perform a shallow copy of customShortcuts into shortcuts.
// This only copies the top-level properties and does not recursively 
// copy nested objects or arrays, which may lead to unintended behavior if 
// customShortcuts contains mutable references.

Object.assign(shortcuts, customShortcuts);

document.addEventListener('keydown', (event) => {
  if (event.ctrlKey || event.altKey || event.metaKey) {
    return;
  }

  if (event.key === shortcuts.search) {
    event.preventDefault();
    focusSearch();
  }

  if (event.key === shortcuts.help) {
    event.preventDefault();
    openHelp();
  }
});

document.querySelectorAll('[data-action]').forEach((input) => {
  input.addEventListener('keydown', (e) => {
    e.preventDefault();
    const action = input.dataset.action;

    shortcuts[action] = e.key;
    customShortcuts[action] = e.key;
    localStorage.setItem(
      'customShortcuts',
      JSON.stringify(customShortcuts)
    );
    input.value = e.key;
  });
});
</script>
Incorrect example
<script>
const SHORTCUTS = Object.freeze({
  search: 's',
  help: 'h',
  newTab: 'n'
});

document.addEventListener('keydown', (event) => {
  const action = Object.keys(SHORTCUTS).find(
    (key) => SHORTCUTS[key] === event.key
  );

  if (action) {
    event.preventDefault();
    executeAction(action);
  }
});
</script>

5. Use the aria-keyshortcuts attribute

Document all available keyboard shortcuts on interactive elements using the aria-keyshortcuts attribute so assistive technologies can announce them. This does not exempt you from meeting SC 2.1.4, but it helps users discover and understand available shortcuts.

Note that support for the title attribute varies across screen readers. For instance, VoiceOver by default has Hints set to ‘Never’ or ‘Speak after delay’, which may prevent the title from being announced. Do not rely solely on title for critical information. Use aria-keyshortcuts instead for announcing keyboard shortcuts.

Correct example
<button aria-keyshortcuts="Ctrl+B" aria-label="Bold text">

<button aria-keyshortcuts="Alt+Shift+F" aria-label="Format document">

<div role="button" tabindex="0" aria-keyshortcuts="s" aria-describedby="shortcut-note">
  Search
</div>

<p id="shortcut-note">
  This shortcut is only active when this button has focus.
</p>
Incorrect example
<button title="Press S to search">
  Search
</button>

<button title="Ctrl+B for bold">

<div tabindex="0">
  Open menu
</div>

Known Limitations

  • Manual-only rule – This rule performs no automated checks and cannot detect single-character shortcuts in JavaScript event listeners, inline onkeydown handlers, or dynamically injected scripts. It depends entirely on developer or tester judgment.
  • Shadow DOM – Event listeners registered inside open or closed shadow roots are not traversed by this rule. Custom elements and web components that bind character key shortcuts internally require separate manual inspection.
  • Third-party and injected scripts – Browser extensions, analytics scripts, chat widgets, and advertising embeds can register global keydown listeners that are invisible to static code analysis. Use DevTools’ Event Listeners panel to audit all active listeners on document.
  • Single-page applications and dynamic content – Frameworks like React, Angular, and Vue may attach and detach keyboard event listeners as components mount and unmount. A snapshot inspection at page load may miss shortcuts added after user interaction or route changes.
  • Canvas and WebGL applications – Keyboard input handled within <canvas> elements often bypasses standard DOM event delegation and may not be inspectable through DevTools. These require source code review or runtime monitoring.
  • Remapping interfaces disguised as documentation – Some applications claim compliance by listing shortcuts in a static help page without providing an actual remapping mechanism. Manual verification must confirm that users can truly change shortcut bindings, not just read about them.

Resources

Rule

  • Audit: accessibility
  • Standard: WCAG
  • Level: A
  • Success Criteria: 2.1.4
  • Rule ID:character_key_shortcuts