@github/hotkey

Install the package via npm to enable hotkey functionality in your project.

$ npm install @github/hotkey

When implementing hotkeys, consider the following accessibility guidelines:

• Character Key Shortcuts: Providing shortcuts can hinder users. Ensure your system allows users to disable or remap hotkeys to comply with WCAG 2.1.4.
• Interactive Elements: Attach hotkeys to interactive and focusable elements whenever possible. If using static elements, follow W3C guidelines for keyboard-accessible actions.

By default, form elements (input, textarea, select) or contenteditable elements call .focus() when triggered, while all other elements trigger a .click().

All elements emit a cancellable hotkey-fire event. You can listen for this event and call event.preventDefault() to override the default behavior with custom logic.

import {install} from '@github/hotkey'

for (const el of document.querySelectorAll('[data-shortcut]')) {
  install(el, el.dataset.shortcut)

  if (el.matches('.frobber')) {
    el.addEventListener('hotkey-fire', event => {
      // prevent the default focus() or click()
      event.preventDefault()

      // Execute custom behavior
      frobulateFrobber(event.target)
    })
  }
}

Use the install function to activate hotkeys on elements. You can either rely on the data-hotkey attribute or pass a specific hotkey string as a second argument. Use uninstall to remove hotkeys from an element.

import {install, uninstall} from '@github/hotkey'

// Install all hotkeys found in the DOM via data-hotkey attribute
for (const el of document.querySelectorAll('[data-hotkey]')) {
  install(el)
}

// Install hotkeys using a custom attribute (e.g., data-shortcut)
for (const el of document.querySelectorAll('[data-shortcut]')) {
  install(el, el.dataset.shortcut)
}

// Unregister hotkeys from elements
for (const el of document.querySelectorAll('[data-hotkey]')) {
  uninstall(el)
}

Hotkey strings follow these rules:

• Key Names: Uses standard W3C KeyboardEvent key names.
• Aliases: Separate multiple hotkeys with a comma (,). Example: a,b.
• Sequences: Separate keys in a sequence with a space. Example: g n.
• Modifiers: Use + to combine modifiers and keys. Order: "Control+Alt+Meta+Shift+KEY".
• Mod Modifier: Mod localizes to Meta on macOS/iOS and Control on Windows/Linux. Do not use Control or Meta in the same string as Mod.
• Special Keys: Use Plus for + and Space for the space bar.
• Comma Key: Use ,, to represent the comma key.
• Case Sensitivity: Use uppercase for keys that require Shift (e.g., Shift+A). Note: Automatic normalization to uppercase for US keyboard layouts is supported.

Use eventToHotkeyString to transform a KeyboardEvent into a standardized NormalizedHotkeyString. This is useful for comparing user input against predefined hotkey strings. The function handles platform-specific quirks, such as mapping macOS symbol layers and uppercase characters back to their base keys, and replaces certain symbols with synthetic names like Space or Plus to maintain compatibility with the hotkey string format.

Supported modifier order: Control, Alt, Meta, Shift.

document.addEventListener('keydown', function(event) {
  if (eventToHotkeyString(event) === 'h') ...
})

Use normalizeHotkey to ensure a raw hotkey string follows the standard format required for comparison with strings produced by eventToHotkeyString.

Normalization performs the following:

• Replaces the Mod modifier with Meta on Apple platforms (Mac, iPod, iPhone, iPad) or Control on other platforms.
• Sorts modifiers into a consistent order: Control, Alt, Meta, Shift.

Note: The platform parameter is primarily intended for mocking navigator.platform in testing environments; otherwise, it defaults to window.navigator.platform.

Use the install function to register an element to respond to specific hotkey sequences. You can provide the hotkey string explicitly, or the function will attempt to read it from the element's data-hotkey attribute.

When install is called for the first time, it attaches a global keydown listener to the document. If the element is a form field, the hotkey will only trigger if the element's id matches the data-hotkey-scope attribute of the target element.