Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lupas/vue3-keypress
Global keypress event handler component for Vue 3 applications.
https://github.com/lupas/vue3-keypress
Last synced: 17 days ago
JSON representation
Global keypress event handler component for Vue 3 applications.
- Host: GitHub
- URL: https://github.com/lupas/vue3-keypress
- Owner: lupas
- Created: 2020-12-27T18:26:06.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2021-09-23T19:34:47.000Z (about 3 years ago)
- Last Synced: 2024-10-11T15:46:14.234Z (about 1 month ago)
- Language: TypeScript
- Size: 1.42 MB
- Stars: 26
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
Awesome Lists containing this project
README
# ⚠️ Breaking Changes with V4 ⚠️
Version 4 introduced breaking changes by making use of the Vue 3 composition API and dropping the component-based approach.
Follow the guide below to setup the module following the new approach.
# Vue Keypress
Want to capture _keydown_, _keypress_ and _keyup_ and events globally in Vue? Nothing easier than that.
The Vue Keypress Component let's you do just that.
Just add the component to the view/component that should start a global keypress handler. When the component gets destroyed, the global event handler also gets removed.
# ‼️ Using Vue 2?
This package only supports Vue 3.
For Vue 2 support, visit the [lupas/vue-keypress](https://github.com/lupas/vue-keypress) package repository.
# How to install?
```bsh
yarn add vue3-keypress
// or
npm i vue3-keypress
```
# How to use in your project?
# Simple Example
```vue
import { useKeypress } from 'vue3-keypress'
import { ref } from 'vue'
setup() {
const someSuccessCallback = ({ keyCode }) => {
// doSomething
}
useKeypress({
keyEvent: "keydown",
keyBinds: [
{
keyCode: "down", // or keyCode as integer, e.g. 40
success: someSuccessCallback,
},
]
})
}
```
# Full Example
```vue
import { useKeypress } from "vue3-keypress";
import { ref } from "vue";
export default {
components: {
KeyBackground,
},
setup() {
const pressedKeyCode = ref(null);
const isSuccess = ref(false);
const isActiveRef = ref(true);
const someSuccessCallback = ({ keyCode }) => {
isSuccess.value = true;
};
const someWrongKeyCallback = ({ event }) => {
isSuccess.value = false;
};
const someAnyKeyCallback = ({ event }) => {
pressedKeyCode.value = event.keyCode;
};
useKeypress({
keyEvent: "keydown",
keyBinds: [
{
keyCode: "left", // or keyCode as integer, e.g. 37
modifiers: ["shiftKey"],
success: someSuccessCallback,
preventDefault: true, // the default is true
},
{
keyCode: "right", // or keyCode as integer, e.g. 39
modifiers: ["shiftKey"],
success: someSuccessCallback,
preventDefault: true, // the default is true
},
],
onWrongKey: someWrongKeyCallback,
onAnyKey: someAnyKeyCallback,
isActive: isActiveRef,
});
return {};
},
};
```
# Config
| Variable | Type | Default | Possible Values | Description |
| ---------- | ------------ | ------- | ------------------------------ | --------------------------------------------------------------------------------- |
| keyEvent | String | 'keyup' | _keydown_, _keypress_, _keyup_ | |
| keyBinds | KeyBind[] | [] | see below | Object containing infos about which keys are expected to be pressed. |
| isActive | Ref(Boolean) | false | true / false | Setups up a listener that activates/deactivates the keypress listener. |
| onWrongKey | Function | null | | Callback that is triggered every time a key is pressed that is not in "keyBinds". |
| onAnyKey | Function | null | | Callback that is triggered every time a key is pressed. |
## Key Binds
| Variable | Type | Default | Possible Values | Description |
| -------------- | --------------- | ------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| keyCode | Number / String | null | [KeyCode as integer](https://keycode.info/) or a [mapped string](https://github.com/lupas/vue3-keypress/blob/master/packages/vue3-keypress/src/key_codes.ts) | Key that should trigger the event. If _null_, any key will trigger event. |
| modifiers | Array | [] | ['_ctrlKey_', '_shiftKey_', '_altKey_', '_metaKey_'] | Keys that needs to be pressed down before the actual key (key Code), e.g. Ctrl+A. |
| preventDefault | Boolean | true | _true_,_false_ | Prevent the default action of the event |
| success | Function | null | | Callback that is triggered when the correct key is pressed. |
The return payload of the callbacks is like so:
```js
{
event: Object, // the official event object
expectedEvent: Object, // your defined props.
message: String // A declarative message on error/success.
}
```