README.md

Vue-Hotkey

@ramstack/vue-hotkey is a lightweight package that simplifies the handling of keyboard shortcuts within Vue applications.

Uses @ramstack/hotkey under the hood.

Installation

Using via NPM

npm install --save @ramstack/vue-hotkey

Using via CDN

<script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@ramstack/vue-hotkey@1/dist/vue-hotkey.min.js"></script>

<script>
    const app = Vue.createApp({
        setup() {
            //
        }
    });

    // Register the hotkey plugin
    app.use(HotkeyPlugin);

    app.mount("#app");
</script>

Using the ES module build

<script type="module">
    import { createApp } from "https://unpkg.com/vue@3/dist/vue.esm-browser.js";
    import { HotkeyPlugin } from "https://cdn.jsdelivr.net/npm/@ramstack/vue-hotkey@1/dist/vue-hotkey.esm.min.js";

    const app = createApp({
        setup() {
            //
        }
    });

    // Register the hotkey plugin
    app.use(HotkeyPlugin);

    app.mount("#app");
</script>

Quick start

Specify the hotkey using directive modifiers.

<script setup>
  import { vHotkey } from "@ramstack/vue-hotkey";
</script>

<template>
  <div v-hotkey.ctrl+k.window.prevent="() => { console.log('Search...') }"></div>
</template>

The hotkey is case-insensitive. 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",
    "/"       : "slash",
    "\\"      : "backslash",
    ";"       : "semicolon",
    "="       : "equal",
    "`"       : "backquote",
    "]"       : "bracketright",
    "["       : "bracketleft",
};

Event modifiers

To simplify the need to call event.preventDefault() or event.stopPropagation() inside event handlers, the vHotkey directive provides appropriate event modifiers.

• .stop
• .prevent
• .passive
• .capture
• .once
• .trusted

<!-- prevent the default behavior for the keyboard event -->
<div v-hotkey.prevent.ctrl+s="event => save(event)"></div>

<!-- the event's propagation will be stopped -->
<div v-hotkey.stop.ctrl+s="event => save(event)"></div>

<!-- modifiers can be chained -->
<div v-hotkey.ctrl+s.prevent.stop.trusted="event => save(event)"></div>

Alternative hotkeys

You can define multiple hotkeys for a single action if you need to. In the example, a single action is triggered for both Ctrl + S and Shift + S. To determine which hotkey triggered the event, access the hotkey property, which contains the string representation of the hotkey.

<div v-hotkey.ctrl+s.shift+s.prevent.stop="event => console.log(event.hotkey)"></div>

Global listening for events

Use the window or document modifiers to listen for events globally at the page level.

<div v-hotkey.ctrl+s.window.prevent="event => save(event)"></div>

Event name to listen for

To specify the event name to be listened for, use the directive's argument. The default event is keydown.

<div v-hotkey:keyup.ctrl+k="() => { console.log('Search...') }"></div>

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" v-hotkey.shift+k="...">
    ...
    <!-- 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" v-hotkey.shift+k="...">
    ...
    <!-- Ignoring hotkeys on form elements -->
    <form data-hotkey-ignore>
        ...
    </form>
</div>

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.