Skip to content

A lightweight Javascript library for handling hotkeys. No external dependencies.

License

Notifications You must be signed in to change notification settings

rameel/ramstack.hotkey.js

Folders and files

NameName
Last commit message
Last commit date

Latest commit

c073e4f · Mar 6, 2025

History

49 Commits
Mar 6, 2025
Mar 6, 2025
Mar 6, 2025
Mar 6, 2025
Mar 6, 2025
Mar 6, 2025
Jan 24, 2024
Mar 6, 2025
Mar 6, 2025
Mar 6, 2025
Mar 6, 2025
Mar 6, 2025
Mar 6, 2025

Repository files navigation

Hotkey

NPM MIT

The @ramstack/hotkey package is a very small and lightweight library for handling hotkeys. The library weighs around 1.3KB and approximately 750 bytes when gzipped.

Installation

Using via NPM

npm install --save @ramstack/hotkey

Using via CDN

<script src="https://cdn.jsdelivr.net/npm/@ramstack/hotkey@1/dist/hotkey.min.js"></script>

Using ES module build

<script type="module">
  import { registerHotkey } from "https://cdn.jsdelivr.net/npm/@ramstack/hotkey@1/dist/hotkey.esm.min.js";
</script>

Quick start

You can specify either the element itself or its selector as the target for key events. For global listening across the entire page, use window or document.

registerHotkey("#app", "Ctrl + K", e => {
  e.preventDefault();
  console.log("Search...");
});

The function returns a cleanup function that allows you to unsubscribe from event listening.

const cleanup = registerHotkey(...);
...

// Unregister the hotkey when they are no longer needed
cleanup();

Exclude elements from hotkey handling

If you wish to prevent hotkey handling on certain elements, add the data-hotkey-ignore attribute to the respective element.

<div id="app">
    ...
    <!-- Ignoring hotkeys on the input element -->
    <input type="text" data-hotkey-ignore>
</div>

Alternatively, apply it to the parent if you want to exclude an entire group of elements at once.

<div id="app">
    ...
    <!-- Ignoring hotkeys on form elements -->
    <form data-hotkey-ignore>
        ...
    </form>
</div>

API

/**
 * Registers a hotkey on the specified target element.
 *
 * @param {EventTarget | string} target - The target element on which the hotkey will be registered.
 * @param {string} hotkey - The combination of keys for the hotkey, e.g., "Ctrl+Alt+Delete".
 * @param {(e: KeyboardEvent) => void} handler - The function to be called when the hotkey is triggered.
 * @param {string} [eventName="keydown"] - The name of the event to listen for (default is "keydown").
 * @param {HotkeyEventListenerOptions | boolean | undefined} [options] - Additional options for the event listener.
 *
 * @returns {() => void} - A function to unregister the hotkey.
 */
function registerHotkey(
    target: EventTarget | string,
    hotkey: string,
    handler: (e: KeyboardEvent) => void,
    eventName?: string,
    options?: HotkeyEventListenerOptions | boolean | undefined): () => void;

Parameters

target (required)

The target element on which the hotkey will be registered. Use window or document for global hotkeys.

registerHotkey(window, "Win + PgUp", e => {
    console.log("Do something");
});

hotkey (required)

The combination of keys for the hotkey, e.g., Ctrl + Alt + Delete The hotkey description is a case-insensitive. Spaces are not important. Standard key names are used. You can find them here Key values for keyboard events

In addition, there are also aliases for some key names:

const aliases: Record<string, string> = {
    "esc"         : "escape",
    "ins"         : "insert",
    "del"         : "delete",
    "up"          : "arrowup",
    "down"        : "arrowdown",
    "right"       : "arrowright",
    "left"        : "arrowleft",
    "pgup"        : "pageup",
    "pgdn"        : "pagedown",
    "break"       : "pause",
    "scroll"      : "scrolllock",
    "scrlk"       : "scrolllock",
    "prtscr"      : "printscreen",
    "win"         : "meta",
    "windows"     : "meta",
    "cmd"         : "meta",
    "command"     : "meta",
    "comma"       : ",",
    "period"      : ".",
    "quote"       : "\"",
    "singlequote" : "'",
    "colon"       : ":",
    "semicolon"   : ";",
    "plus"        : "+",
    "minus"       : "-",
    "tilde"       : "~",
    "equal"       : "=",
    "slash"       : "/"
};

handler (required)

The function to be called when the hotkey is triggered.

The value of this inside the handler will be a reference to the element. It will be the same as the value of the currentTarget property of the event argument that is passed to the handler.

registerHotkey("#el", "Ctrl + K", function(e) {
    console.log(e.currentTarget === this); // logs true
});

As a reminder, arrow functions do not have their own this context.

registerHotkey("#el", "Ctrl + K", e => {
    console.log(e.currentTarget === this); // logs false
});

eventName (optional, default: 'keydown')

The name of the event to listen for. You can subscribe to events on keydown (used by default) or keyup.

registerHotkey(window, "Ctrl + Up", e => {
    e.preventDefault();
    ...
}, "keyup");

options (optional)

Additional options for the event listener. See Options.

/**
 * Extended options for hotkey event listeners.
 */
export interface HotkeyEventListenerOptions extends AddEventListenerOptions {
    /**
     * If specified, ensures that only trusted events are handled.
     */
    trusted?: boolean;
}

The trusted option ensures that only events marked as trusted are handled. This can help prevent synthetic or untrusted events from triggering hotkeys.

registerHotkey(window, "Ctrl + S", e => {
    e.preventDefault();
    console.log("Saving...");
}, "keydown", { trusted: true });

In this example, the hotkey will only trigger for events that are marked as trusted, preventing manually dispatched or synthetic events from interfering.

Returns

A function that, when called, unregisters the hotkey.

const cleanup = registerHotkey(...);
...

// Unregister the hotkey when they are no longer needed
cleanup();

Contributions

Bug reports and contributions are welcome.

License

This package is released as open source under the MIT License. See the LICENSE file for more details.

About

A lightweight Javascript library for handling hotkeys. No external dependencies.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published