Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/lupas/vue3-keypress

Global keypress event handler component for Vue 3 applications.
https://github.com/lupas/vue3-keypress

Last synced: 15 days ago
JSON representation

Global keypress event handler component for Vue 3 applications.

Awesome Lists containing this project

README

        


Downloads
Version
License

# ⚠️ 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.
}
```