Skip to main content

Quick Start Guide

Initialize OpenKeyNav once to add its keyboard operation and navigation modes to a website or web app.

1. Add the library​

Using npm:

import OpenKeyNav from 'openkeynav';

const openKeyNav = new OpenKeyNav();
openKeyNav.init();

Using the browser build:

<script src="https://cdn.jsdelivr.net/npm/openkeynav/dist/openkeynav.umd.min.js"></script>
<script>
  const openKeyNav = new OpenKeyNav();
  openKeyNav.init();
</script>

Place one instance at the persistent document or application root.

2. Turn the command layer on​

Press Shift + O to turn OpenKeyNav on. The same command turns it off.

OpenKeyNav keeps its character commands inactive until a user enables them. This persistent on/off mechanism supports the turn-off option in WCAG 2.1 Success Criterion 2.1.4: Character Key Shortcuts.

Add a visible explanation or control to the final interface so users can discover the feature and its off command.

When focus is inside an input, textarea, or contenteditable region and no OpenKeyNav mode is active, OpenKeyNav suppresses its ordinary K, M, O, H, S, and 1 through 6 commands. After the command layer is on, hold Ctrl to route one intentionally—for example, Ctrl + K for Click Mode. The global activation command becomes Ctrl + Shift + O in these fields.

Add OpenKeyNav's toolbar​

OpenKeyNav includes a compact toolbar that keeps the current activation, shortcut-guide, and mode-exit commands visible without application-specific state wiring. Place one empty host in a stable part of the application:

<aside aria-label="OpenKeyNav keyboard commands">
  <div class="openKeyNav-toolBar"></div>
</aside>

init() fills the host and updates it as OpenKeyNav's state changes. It also initializes a matching host inserted later by a client-side framework. Pair the toolbar's contextual prompts with the complete commands enabled by the application. See Add the OpenKeyNav Toolbar for lifecycle, placement, accessibility, and layout guidance.

3. Use the modes​

  • Shortcut Guide: Press O after turning the command layer on.
  • Click Mode: Press K, then type the label displayed beside a detected target. OpenKeyNav focuses or activates the selected target.
  • Heading Navigation: Press H for the next heading. Use 1 through 6 to navigate by heading level. Hold Shift with a heading command to move backward.
  • Scroll Navigation: Press S to move among detected scrollable regions. Press Shift + S to move backward.
  • Structural Navigation: Press R to navigate existing focus targets through page structure.
  • Move Mode: After configuring valid sources and destinations, press M, select a source label, and select a destination label.
  • Exit: Press Escape or Q to leave Click Mode, Move Mode, or the Shortcut Guide. Press Alt + R to exit Structural Navigation reliably.

4. Verify action coverage​

Open each relevant application state and invoke Click Mode. Confirm that:

  1. every intended target receives a label;
  2. label selection performs the expected action once;
  3. focus and status feedback leave the user ready for the next step; and
  4. each action has a verified keyboard path through Click Mode, conventional behavior, or application-specific handling.

Configure Move Mode for endpoint-based movement workflows. Repeat the tests after route changes, asynchronous updates, dialogs, validation errors, and responsive layout changes.

5. Review diagnostic candidates​

Click Mode diagnostics are enabled by default. The heuristic marks actions selected for manual keyboard review with a red outline and tooltip, and Click Mode includes each marked target in its direct-selection labels.

For each review candidate, check its purpose, semantics, accessible name, role, state, focus behavior, OpenKeyNav activation outcome, and place in the complete task. Use the heuristic for triage, then review every expected action across the complete workflow.

Switch to standard Click Mode labels for production:

openKeyNav.init({
  debug: {
    keyboardAccessible: false,
  },
});

Continue with Accessibility and WCAG Support for the broader verification workflow or the ADA Title II guide for public-sector implementation planning.