Repository files navigation

<buttondata-hotkey="Shift+?">Show help dialog</button>

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

The hotkey can be scoped to a form field:

<buttondata-hotkey-scope="text-area"data-hotkey="Meta+d"onclick="alert('clicked')">  press meta+d in text area to click this button</button><textareaid="text-area">text area</textarea>

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.

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

$ npm install @github/hotkey

<!-- Single character hotkey: triggers when "j" is pressed--><ahref="/page/2"data-hotkey="j">Next</a><!-- Multiple hotkey aliases: triggers on both "s" and "/" --><ahref="/search"data-hotkey="s,/">Search</a><!-- Key-sequence hotkey: triggers when "g" is pressed followed by "c"--><ahref="/rails/rails"data-hotkey="g c">Code</a><!-- Hotkey with modifiers: triggers when "Control", "Alt", and "h" are pressed at the same time --><ahref="/help"data-hotkey="Control+Alt+h">Help</a><!-- Special "Mod" modifier localizes to "Meta" on mac, "Control" on Windows or Linux--><ahref="/settings"data-hotkey="Mod+s">Search</a>

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

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)}

By default form elements (such asinput,textarea,select) or elements withcontenteditable will callfocus() when the hotkey is triggered. All other elements trigger aclick(). All elements, regardless of type, will emit a cancellablehotkey-fire event, so you can customize the behaviour, if you so choose:

for(constelofdocument.querySelectorAll('[data-shortcut]')){install(el,el.dataset.shortcut)if(el.matches('.frobber')){el.addEventListener('hotkey-fire',event=>{// ensure the default `focus()`/`click()` is prevented:event.preventDefault()// Use a custom behaviour insteadfrobulateFrobber(event.target)})}}

1. Hotkey matches against theevent.key, and uses standard W3C key names for keys and modifiers as documented inUI 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 hotkeya,b would activate if the user typeda orb.
4. Multiple keys separated by a blank space represent a key sequence. For example the hotkeyg n would activate when a user types theg key followed by then 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. "Mod" is a special modifier that localizes toMeta on MacOS/iOS, andControl on Windows/Linux.
   1. "Mod+" can appear in any order in a hotkey string. For example:"Mod+Alt+Shift+KEY"
   2. Neither theControl orMeta modifiers should appear in a hotkey string withMod.
7. "Plus" and"Space" are special key names to represent the+ and keys respectively, because these symbols cannot be represented in the normal hotkey string syntax.
8. You can use the comma key, as a hotkey, e.g.a,, would activate if the user typeda or,.Control+,,x would activate forControl+, orx.
9. "Shift" should be included if it would be held and the key is uppercase: ie,Shift+A notA
   1. MacOS outputs lowercase key names whenMeta+Shift is held (ie,Meta+Shift+a). In an attempt to normalize this,hotkey will automatically map these key names to uppercase, so the uppercase keys should still be used (ie,"Meta+Shift+A" or"Mod+Shift+A").However, this normalization only works on US keyboard layouts.

The following hotkey would match if the user typed the key sequencea and thenb, OR if the user held down theControl,Alt and/ keys at the same time.

'a b,Control+Alt+/'

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

Two-key-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 installnpm test

Distributed under the MIT license. See LICENSE for details.