https://github.com/undecaf/vue-hotkey
A flexible Vue hotkey directive
https://github.com/undecaf/vue-hotkey
directive hotkey keyboard-shortcuts shortkey vue
Last synced: 4 months ago
JSON representation
A flexible Vue hotkey directive
- Host: GitHub
- URL: https://github.com/undecaf/vue-hotkey
- Owner: undecaf
- License: mit
- Created: 2020-08-26T14:15:24.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2021-07-24T08:06:37.000Z (about 5 years ago)
- Last Synced: 2025-10-25T09:51:33.702Z (10 months ago)
- Topics: directive, hotkey, keyboard-shortcuts, shortkey, vue
- Language: JavaScript
- Homepage:
- Size: 1.74 MB
- Stars: 0
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# A flexible Vue hotkey directive
This directive, `v-hotkey`, transforms hotkey keystrokes to an event on a target element or to
a function call. It offers the following features:
+ When placed on a Vue component (as opposed to a plain HTML element), `v-hotkey` can also target
an inner element, determined by a CSS selector.
+ The target element can receive an event, or a method can be called with the target
element as argument.
+ The hotkey mapping is maintained for the lifetime of the element on which
`v-hotkey` is placed. Thus, hotkey mappings appear and disappear automatically together
with the elements they are placed on.
+ Hotkeys can be combinations of `Ctrl`, `Alt`, `Shift` and `Meta` with a character or a
special [key value](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values).
Multiple hotkeys can be mapped to the same action.
+ Hotkeys will override browser shortcuts if possible.
+ High performance: the `keydown` event overhead is very low and practically independent of the number
of hotkeys (in [this example](https://undecaf.github.io/vue-hotkey/example/),
over 800 hotkeys are defined).
+ The configuration can be changed dynamically.
+ The directive can be disabled.
An online example demonstrating `v-hotkey` for plain HTML and Vue Material components
[is available here](https://undecaf.github.io/vue-hotkey/example/)
([example source code](https://github.com/undecaf/vue-hotkey/blob/master/src/components/Demo.vue)).
## Installation
As a module:
```shell script
$ npm install @undecaf/vue-hotkey
or
$ yarn add @undecaf/vue-hotkey
```
Included as ``:
```html
<script src="https://cdn.jsdelivr.net/npm/@undecaf/vue-hotkey/dist/directives.min.js">
```
## Usage
### Registering the directive
```javascript 1.8
import hotkey from 'vue-hotkey'
Vue.use(hotkey)
```
### Configuration
`v-hotkey` requires a configuration object, or a string or an array (sets the `keys` property).
Unspecified options get default values.
The configuration object supports the following properties:
| Name | Type | Description | Default |
|------|------|-------------|---------|
| `enabled` | `Boolean` | Enables the directive if truthy. | `true` |
| `keys` | `String` or `Array` | Hotkey(s) in the format [Ctrl+][Shift+][Alt+][Meta+]key_value.
Plain characters should have at least one `Ctrl`, `Alt` or `Meta` modifier in order to avoid conflicts with input elements (see [this example](#using-plain-characters-as-hotkeys) for an exception). `Shift` is irrelevant for plain characters as they are matched case-insensitively.
Hotkeys will override browser shortcuts if possible.| none, must be specified |
| `action` | `String` or `Event` or `Function` | An event name, an [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event) object, or a function to be called.
The function receives the target element as argument, and `this` references the surrounding Vue component's `vm`. | `'click'` |
| `selector` | `String` | The first element matching this selector (starting with the element on which `v-hotkey` is placed) becomes the target for `action`. | `'*'` |
| `priority` | `Number` | Priority in relation to other hotkey configurations.
If the same hotkey has been mapped several times then the configuration with the highest priority wins. | `0` |
Property changes after binding are taken into account.
### Examples
#### Generating button clicks
Hotkeys that click an HTML button and a [Vue Material Button](https://vuematerial.io/components/button):
```html
Submit
Save
```
No `target` is required for `` since this component resolves to the target
(a ``) anyway.
#### Calling a function in response to a hotkey
Toggling a checkbox value:
```html
Show details (Ctrl-D to toggle)
```
Please note that `action: details = !details` would lead to an infinite render loop, and
`action: el => el.checked = !el.checked` would not toggle variable `details`.
#### Using plain characters as hotkeys
Entering search text after a leading `/` (inspired by the [Vuetify](https://vuetifyjs.com/) homepage):
```html
Search ("/" to focus)
```
Plain-character hotkeys are disabled automatically on inputs and contenteditable elements
so that they can be entered in these elements.
`v-hotkey` could have been placed also on ``, omitting the `selector` because ``
resolves to ``.
#### Placing multiple hotkey mappings on the same element
Multiple `v-hotkey` directives can be placed on the same element if a unique argument is appended
to each directive:
```vue
...
Save
Exit
...
```
#### Clicking an element inside an opaque component
Although the inner structure of the [Vue Material confirms](https://vuematerial.io/components/dialog)
component is not exposed we can still map hotkeys to the buttons:
```html
```
#### Context-sensitive mapping
If the [Vue Material dialog](https://vuematerial.io/components/dialog) is showing then `Ctrl-S` clicks
the `Save` button in the dialog; otherwise `Ctrl-S` clicks the `Save` button in the surrounding component:
```vue
...
Save
...
...
Save
```
## License
Software: [MIT](http://opensource.org/licenses/MIT)
Documentation: [CC-BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/)