vue-global-events
Add shortcuts by listening to events on the document, anywhere
This is the version for Vue 3, if you are looking for the Vue 2 version, take a look at the v1
branch
Sponsors
Bronze
Installation
yarn add vue-global-events
npm install vue-global-events
Demo
Idea
Thanks to Vue’s event modifiers, handling events is extremely easy however, you’re limited to DOM element events.
We decided to change that, so now you can register global events (for example application shortcuts) just like you would listen to events on a component. No need to worry about removing them either. You can toggle the events with a single v-if
. Works with SSR too.
Usage
import { GlobalEvents } from 'vue-global-events'
// register globally
app.component('GlobalEvents', GlobalEvents)
// or locally
export default {
components: { GlobalEvents },
// rest of your component
}
After that you can register global events like this:
<GlobalEvents
v-if="listenersConnected"
@keyup.ctrl.tab="nextTab"
@keyup.ctrl.shift.tab="previousTab"
@keyup.space="pause"
@contextmenu="openMenu"
/>
Props
target
Target element where addEventListener
is called on. It's a String that refers to a global variable like document
or window
. This allows you to add events to the window
instead of document
.
- type:
String
- default:
'document'
Warning: This prop is not reactive. It should be provided as a static value. If you need it to be reactive, add a key
attribute with the same value:
<GlobalEvents :target="target" :key="target" />
filter
Function to prevent any event from being executed based on anything related to the event like the element that triggered it, the name, or the handler.
- type:
Function
- default:
() => true
arguments
-
event
: Native Event Object -
handler
: method passed toGlobalEvents
component -
eventName
: event name that was attached to the target (See above)
filter
should return false
to prevent the execution of a handler. For example, you can avoid the calls if the event is triggered by an <input>
:
<GlobalEvents
:filter="(event, handler, eventName) => event.target.tagName !== 'INPUT'"
@keyup.prevent.space.exact="nextTab"
/>
In the example above event
would be the native keyup
Event Object, handler
would be the method nextTab
and eventName
would be the string keyup
.
Advice / Caveats
- Always
.prevent
events with.ctrl
and other modifiers as browsers may be using them as shortcuts. - Do not use shortcuts that are used by the system or that the browser does not allow you to
.preventDefault()
. The list includesCtrl+Tab
/Cmd+Tab
,Ctrl+W
/Cmd+W
. You can find more information in this StackOverflow answer. - Prefer using actual characters to keyCodes whenever possible:
@keydown.+
for detecting the plus sign. This is important because symbols and numbers on the digit row will provide different keyCodes depending on the layout used. - About using
keyup
with modifiers like.ctrl
or.shift
: the keyup event is triggered when a key is released and that's also when theevent.ctrlKey
is checked, which if you just released, will be false. This is becausectrl
,shift
andalt
are checked differently. If you want to trigger on thekeyup
event of a modifier, you need to use its keycode (check it here. For example, for thectrl
key, that would be:@keyup.17
. You can also use the advice above this one to provide it a name like ctrlkey.
Development
Run tests in watch mode:
yarn jest --watch
Authors
Damian Dulisz @shentao
Eduardo San Martin Morote @posva