Skip to main content

Basic Configuration

Configure OpenKeyNav's typeable labels, command keys, and version-support telemetry from the application entry point.

Configuring Typeable Labels​

You can customize the appearance and behavior of typeable labels by modifying the spot configuration object. This includes settings for font color, background color, inset color, font size, and arrow size.

const config = {
    spot: {
        fontColor: 'white',       // Color of the text
        backgroundColor: '#333',  // Background color of the label
        insetColor: '#000',       // Color of the inset shadow
        fontSize: 'inherit',      // Font size of the label
        arrowSize_px: 4           // Size of the arrow pointing to the element
    }
};

openKeyNav.init(config);

Keys Configuration​

OpenKeyNav provides default key bindings for its modes and lets the application replace them with commands that fit its interaction design.

Default Key Bindings and Their Functions​

  • escape: q - Alternative escape key, useful when the escape key is not easily accessible.
  • click: k - Enter click mode to click on clickable elements, such as links.
  • scroll: s - Focus on the next scrollable region.
  • move: m - Enter Move Mode for configured keyboard movement and drag-and-drop workflows.
  • heading: h - Focus on the next heading.

How to Customize Keys​

You can override the default key bindings by specifying a new key configuration:

const config = {
    keys: {
        escape: 'e',   // Custom escape key
        click: 'c',    // Custom click mode key
        scroll: 'w',   // Custom scroll mode key
        move: 'd',     // Custom move mode key
        heading: 'n'   // Custom heading navigation key
    }
};

openKeyNav.init(config);

This configuration gives the application one place to align OpenKeyNav labels and commands with its interaction design.

Telemetry Configuration​

OpenKeyNav sends a version support event by default on non-localhost pages. Disable that request during initialization with telemetry.enabled:

openKeyNav.init({
  telemetry: {
    enabled: false,
  },
});

See the telemetry API reference for the default behavior.

info

Turn OpenKeyNav on

After the page loads, press Shift + O to turn OpenKeyNav on or 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.