Repository files navigation

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

By default, hotkeys are extracted from a target element'sdata-hotkeyattribute, but this can be overridden by passing the hotkey to the registeringfunction (install) as a parameter.

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

Two-keypress sequences such asg c andg i are storedunder 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, bothg c andc could be available as hotkeys on thesame page, butg c andg can't coexist. If the user pressesg, thec hotkey will be unavailable for 1500 ms while wewait for eitherg c org i.

Please note that adding this functionality to your site can be a drawback forcertain users. Providing a way in your system to disable hotkeys or remapthem makes sure that those users can still use your site (given that it'saccessible to those users).

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

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

$ npm install @github/hotkey

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

Seethe list ofKeyboardEvent key values for a list of supported key values.

If the user is currently within a typeable element (an input or textarea) then hotkeys will not fire. This behavior is intentional as these typeable elements will receive a lot of input which may accidentally trigger keyboard shortcuts. In other words - global hotkeys by design will not fire in areas where the user is likely to type.

It is possible to override this behavior by addingdata-hotkey-for which points to an ID of a form element. A element withdata-hotkey-for specifically scopes the hotkey activation only to the element which it points to. In other words - these aren't global hotkeys, but are specifically scopes to an element's focus. This allows you to still have shortcut behaviors for an element, but using an opt-in pattern.

<buttondata-hotkey="j">This will fire when input is not focussed</button><buttondata-hotkey="j"data-hotkey-for="my_id">This will fire when only if input is focussed</button><inputid="my_id">

import{install}from'@github/hotkey'// Install all the hotkeys on the pagefor(constelofdocument.querySelectorAll('[data-hotkey]')){install(el)}

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

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

To unregister a hotkey from an element, useuninstall:

import{uninstall}from'@github/hotkey'for(constelofdocument.querySelectorAll('[data-hotkey]')){uninstall(el)}

npm installnpm test

Distributed under the MIT license. See LICENSE for details.