https://github.com/rameel/ramstack.vue-hotkey.js
A lightweight package simplifies the handling of keyboard shortcuts within Vue applications. No external dependencies
https://github.com/rameel/ramstack.vue-hotkey.js
hotkey shortcuts shortkey
Last synced: 11 months ago
JSON representation
A lightweight package simplifies the handling of keyboard shortcuts within Vue applications. No external dependencies
- Host: GitHub
- URL: https://github.com/rameel/ramstack.vue-hotkey.js
- Owner: rameel
- License: mit
- Created: 2024-01-25T23:36:07.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-03-06T21:26:16.000Z (about 1 year ago)
- Last Synced: 2025-03-06T21:26:42.103Z (about 1 year ago)
- Topics: hotkey, shortcuts, shortkey
- Language: TypeScript
- Homepage:
- Size: 73.2 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Vue-Hotkey
[](https://www.npmjs.com/package/@ramstack/vue-hotkey)
[](https://github.com/rameel/ramstack.vue-hotkey.js/blob/main/LICENSE)
`@ramstack/vue-hotkey` is a lightweight package that simplifies the handling of keyboard shortcuts within Vue applications.
Uses [@ramstack/hotkey](https://github.com/rameel/hotkey) under the hood.
## Installation
### Using via NPM
```sh
npm install --save @ramstack/vue-hotkey
```
### Using via CDN
```html
const app = Vue.createApp({
setup() {
//
}
});
// Register the hotkey plugin
app.use(HotkeyPlugin);
app.mount("#app");
```
### Using the ES module build
```html
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");
```
## Quick start
Specify the hotkey using directive modifiers.
```vue
import { vHotkey } from "@ramstack/vue-hotkey";
{ console.log('Search...') }">
```
The hotkey is case-insensitive. Standard key names are used.
You can find them here [Key values for keyboard events](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values)
In addition, there are also aliases for some key names:
```js
const aliases: Record = {
"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" : "/"
};
```
### 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`
```vue
save(event)">
save(event)">
save(event)">
```
### 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 of hotkeys triggered the event, access the `hotkey` property,
which contains the string representation of the hotkey.
```vue
console.log(event.hotkey)">
```
### Global listening for events
Use the `window` or `document` modifiers to listen for events globally at the page level.
```vue
save(event)">
```
### Event name to listen for
To specify the event name to be listened for, use the argument directive.
The default event is `keydown`.
```vue
{ console.log('Search...') }">
```
### 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.
```html
...
```
Alternatively, apply it to the parent if you want to exclude an entire group of elements at once.
```html
...
...
```
## Contributions
Bug reports and contributions are welcome.
## License
This package is released as open source under the **MIT License**.
See the [LICENSE](https://github.com/rameel/ramstack.vue-hotkey.js/blob/main/LICENSE) file for more details.