Skip to content
Trigger an action on an element with a keyboard shortcut.
JavaScript
Branch: master
Clone or download
Latest commit 00f1003 Oct 25, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src Trigger click on anything that are not form fields Oct 23, 2019
test add radio button input element test Feb 14, 2019
.eslintrc.json init Jan 16, 2019
.flowconfig run `flow init` Jan 21, 2019
.gitignore ignore dist folder Jan 16, 2019
.travis.yml add travis configuration Jan 24, 2019
LICENSE init Jan 16, 2019
README.md
index.d.ts add typescript definition file Jul 2, 2019
package-lock.json 1.3.0 Oct 25, 2019
package.json 1.3.0 Oct 25, 2019
prettier.config.js init Jan 16, 2019
rollup.config.js compile files in src/ to dist/ using rollup Jan 16, 2019

README.md

Hotkey Behavior

Trigger an action on a target element when a key or sequence of keys is pressed on the keyboard. This triggers a focus event on form fields, or a click event on others.

By default, hotkeys are extracted from a target element's data-hotkey attribute, but this can be overridden by passing the hotkey to the registering function (install) as a parameter.

Multiple hotkeys are separated by a ,; key combinations are separated by a +; and key sequences are separated by a space.

Two-keypress sequences such as g c and g i are stored under the 'g' key in a nested object with 'c' and 'i' keys.

mappings =
  'c'     : <a href="/rails/rails/issues/new" data-hotkey="c">New Issue</a>
  'g'     :
    'c'   : <a href="/rails/rails" data-hotkey="g c">Code</a>
    'i'   : <a href="/rails/rails/issues" data-hotkey="g i">Issues</a>

In this example, both g c and c could be available as hotkeys on the same page, but g c and g can't coexist. If the user presses g, the c hotkey will be unavailable for 1500 ms while we wait for either g c or g i.

Accessibility considerations

Character Key Shortcuts

Please note that adding this functionality to your site can be a drawback for certain users. Providing a way in your system to disable hotkeys or remap them makes sure that those users can still use your site (given that it's accessible to those users).

See "Understanding Success Criterion 2.1.4: Character Key Shortcuts" for further reading on this topic.

Interactive Elements

Wherever possible, hotkeys should be add to interactive and focusable elements. If a static element must be used, please follow the guideline in "Adding keyboard-accessible actions to static HTML elements".

Installation

$ npm install @github/hotkey

Usage

HTML

<a href="/page/2" data-hotkey="j">Next</a>
<a href="/help" data-hotkey="Control+h">Help</a>
<a href="/rails/rails" data-hotkey="g c">Code</a>
<a href="/search" data-hotkey="s,/">Search</a>

See the list of KeyboardEvent key values for a list of supported key values.

JS

import {install} from '@github/hotkey'

// Install all the hotkeys on the page
for (const el of document.querySelectorAll('[data-hotkey]')) {
  install(el)
}

Alternatively, the hotkey(s) can be passed to the install function as a parameter e.g.:

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

To unregister a hotkey from an element, use uninstall:

import {uninstall} from '@github/hotkey'

for (const el of document.querySelectorAll('[data-hotkey]')) {
  uninstall(el)
}

Development

npm install
npm test

License

Distributed under the MIT license. See LICENSE for details.

You can’t perform that action at this time.