Hotkey

Trigger an action on an element with a keyboard shortcut.

Keyboard
github/hotkeygithub.github.io/hotkey/examples/@github/hotkey

README

Hotkey Behavior


  1. ``` html
  2. <button data-hotkey="Shift+?">Show help dialog</button>
  3. ```

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

The hotkey can be scoped to a form field:

  1. ``` html
  2. <button data-hotkey-scope="text-area" data-hotkey="Meta+d" onclick="alert('clicked')">
  3.   press meta+d in text area to click this button
  4. </button>
  5. <textarea id="text-area">text area</textarea>
  6. ```

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.

How is this used on GitHub?


All shortcuts (for example g i, ., Meta+k) within GitHub use hotkey to declare shortcuts in server side templates. This is used on almost every page on GitHub.

Installation


  1. ```
  2. $ npm install @github/hotkey
  3. ```

Usage

HTML


  1. ``` html
  2. <a href="/page/2" data-hotkey="j">Next</a>
  3. <a href="/help" data-hotkey="Control+h">Help</a>
  4. <a href="/rails/rails" data-hotkey="g c">Code</a>
  5. <a href="/search" data-hotkey="s,/">Search</a>
  6. ```

See [the list of KeyboardEvent key values](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) for a list of supported key values.

JS


  1. ``` js
  2. import {install} from '@github/hotkey'

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

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

  1. ``` js
  2. for (const el of document.querySelectorAll('[data-shortcut]')) {
  3.   install(el, el.dataset.shortcut)
  4. }
  5. ```

To unregister a hotkey from an element, use uninstall:

  1. ``` js
  2. import {uninstall} from '@github/hotkey'

  4. for (const el of document.querySelectorAll('[data-hotkey]')) {
  5.   uninstall(el)
  6. }
  7. ```

By default form elements (such as input,textarea,select) or elements with contenteditable will call focus() when the hotkey is triggered. All other elements trigger a click(). All elements, regardless of type, will emit a cancellable hotkey-fire event, so you can customize the behaviour, if you so choose:

  1. ``` js
  2. for (const el of document.querySelectorAll('[data-shortcut]')) {
  3.   install(el, el.dataset.shortcut)
  4.   
  5.   if (el.matches('.frobber')) {
  6.     el.addEventListener('hotkey-fire', event => {
  7.       // ensure the default `focus()`/`click()` is prevented:
  8.       event.preventDefault()
  9.       
  10.       // Use a custom behaviour instead
  11.       frobulateFrobber(event.target)
  12.     })
  13.   }
  14. }
  15. ```

Hotkey string format


1. Hotkey matches against the event.key, and uses standard W3C key names for keys and modifiers as documented in UI Events KeyboardEvent key Values.
2. At minimum a hotkey string must specify one bare key.
3. Multiple hotkeys (aliases) are separated by a ,. For example the hotkey a,b would activate if the user typed a or b.
4. Multiple keys separated by a blank space represent a key sequence. For example the hotkey g n would activate when a user types the g key followed by the n key.
5. Modifier key combos are separated with a + and are prepended to a key in a consistent order as follows: Control+Alt+Meta+Shift+KEY.
6. You can use the comma key , as a hotkey, e.g. a,, would activate if the user typed a or ,. Control+,,x would activate for Control+, or x.

Example


The following hotkey would match if the user typed the key sequence a and then b, OR if the user held down the Control, Alt and / keys at the same time.

  1. ``` js
  2. "a b,Control+Alt+/"
  3. ```

🔬 Hotkey Mapper is a tool to help you determine the correct hotkey string for your key combination: https://github.github.io/hotkey/examples/hotkey_mapper.html

Key-sequence considerations


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

  1. ```
  2. mappings =
  3.   'c'     : <a href="/rails/rails/issues/new" data-hotkey="c">New Issue</a>
  4.   'g'     :
  5.     'c'   : <a href="/rails/rails" data-hotkey="g c">Code</a>
  6.     'i'   : <a href="/rails/rails/issues" data-hotkey="g i">Issues</a>
  7. ```

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".

Development


  1. ```
  2. npm install
  3. npm test
  4. ```

License


Distributed under the MIT license. See LICENSE for details.