Registry / web-framework / vue-global-events

vue-global-events

library3.0.1jsnpmunverified

Vue Global Events is a lightweight library for Vue 3 that enables developers to register global keyboard and mouse events directly within Vue templates using familiar Vue event modifiers. It abstracts away the complexities of `addEventListener` and `removeEventListener` on `document` or `window`, automatically handling event lifecycle management in sync with component unmounting. The current stable version is 3.0.1, specifically designed for Vue 3. It differs from manual global event handling by leveraging Vue's declarative syntax and reactivity system, allowing events to be conditionally enabled/disabled with `v-if` and ensuring proper cleanup, including support for Server-Side Rendering (SSR). While there isn't a strict release cadence, updates are typically made to align with new Vue versions or to introduce minor enhancements and bug fixes.

web-framework

npm install vue-global-events

github ↗package ↗

INSTALL

IMPORT

SIG · VUE-GLOBAL-EVENTS

vue-global-events

web-frameworkjavascriptv3.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

GlobalEvents

✓ import { GlobalEvents } from 'vue-global-events'

✗ const { GlobalEvents } = require('vue-global-events')

The library primarily uses ES Modules. For Vue 3, ESM is the standard import method.

GlobalEvents (global registration)

✓ import { createApp } from 'vue'; import { GlobalEvents } from 'vue-global-events'; const app = createApp(...); app.component('GlobalEvents', GlobalEvents);

Registering the component globally allows its use without explicit local imports in every component where it's needed.

This quickstart demonstrates how to install, register, and use the `GlobalEvents` component to listen for global keyboard shortcuts like `Ctrl+Space` and `Alt+S` within a Vue 3 application. It also shows conditional event listening with `v-if` and includes a basic input field to illustrate event filtering caveats.

import { createApp, ref } from 'vue'; import { GlobalEvents } from 'vue-global-events'; const App = { components: { GlobalEvents }, setup() { const message = ref('Press Ctrl+Space to toggle, or Alt+S for a message.'); const showGlobalEvents = ref(true); const toggleEvents = () => { showGlobalEvents.value = !showGlobalEvents.value; message.value = `Global events are now ${showGlobalEvents.value ? 'enabled' : 'disabled'}.`; }; const showAltSMessage = () => { alert('Alt+S was pressed globally!'); message.value = 'Alt+S was pressed!'; }; return { message, showGlobalEvents, toggleEvents, showAltSMessage, }; }, template: ` <div> <h1>Vue Global Events Demo</h1> <p>{{ message }}</p> <button @click="toggleEvents">Toggle Global Events (Current: {{ showGlobalEvents ? 'ON' : 'OFF' }})</button> <GlobalEvents v-if="showGlobalEvents" @keyup.ctrl.space.prevent="toggleEvents" @keyup.alt.s="showAltSMessage" @keydown.prevent.page-down="() => message = 'Page Down was pressed!'" /> <div style="margin-top: 20px;"> <input type="text" placeholder="Type here to avoid triggering events" /> </div> </div> ` }; createApp(App).mount('#app');

Debug

Known issues

breakingVersion 3.x is designed exclusively for Vue 3. If you are using Vue 2, you must use the `v1` branch or an earlier 2.x version of `vue-global-events`. The API for Vue 3 is largely compatible with earlier versions, but the underlying Vue runtime is different.

fix

For Vue 2 projects, install `vue-global-events@^2.0.0` or refer to the `v1` branch for specific Vue 2 instructions. For Vue 3, simply install `vue-global-events`.

affects: >=3.0.0

gotchaThe `target` prop, which specifies the element to attach listeners (e.g., 'document' or 'window'), is not reactive by default. Changing its value will not re-attach listeners to a new target unless explicitly forced.

fix

If the `target` prop needs to be reactive, you must bind a `key` attribute to the `GlobalEvents` component with the same reactive value. This forces Vue to re-render and re-mount the component when the `key` changes, effectively reapplying the listeners to the new target.

affects: >=2.0.0

gotchaCertain browser and system shortcuts cannot be `preventDefault()`ed, even with Vue's `.prevent` modifier. Common examples include `Ctrl+Tab`/`Cmd+Tab` for switching browser tabs and `Ctrl+W`/`Cmd+W` for closing tabs.

fix

Avoid using shortcuts that are reserved by the operating system or browser, as they will override your application's handlers. Always test critical shortcuts across different browsers and OSes.

affects: >=1.0.0

gotchaWhen defining global event listeners, always use the `.prevent` modifier with events involving control keys (e.g., `.ctrl`, `.alt`, `.meta`) to prevent default browser actions that might interfere with your application's desired behavior.

fix

Add `.prevent` to your event listener: `@keyup.ctrl.space.prevent="myHandler"`.

affects: >=1.0.0

gotchaPrefer using actual character keys (e.g., `@keydown.+` for the plus sign) instead of `keyCodes` when possible. `keyCodes` can vary depending on the keyboard layout, leading to inconsistent behavior for users with different regional settings.

fix

Specify the literal key character in your event modifier (e.g., `@keyup..` for a period) instead of relying on deprecated `keyCode` values or guessing based on layout.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'component') or 'GlobalEvents' is not defined

The `GlobalEvents` component was not registered with the Vue application (either globally or locally within the component where it's used).

fix

Ensure `app.component('GlobalEvents', GlobalEvents)` is called for global registration, or include `GlobalEvents` in the `components` option of your consuming Vue component.

Global event not firing when expected, or firing when it shouldn't (e.g., in an input field).

The `filter` prop is preventing the event handler from executing, or the event target is not what's expected.

fix

Check the `filter` function provided to `GlobalEvents`. If you want events to fire even in inputs, ensure your `filter` function does not exclude them (the default is `() => true`). Also, verify the `target` prop is correctly set to 'document' or 'window' as intended.

Browser default action (e.g., scrolling, tab switching) still occurs despite adding a global event listener.

The `.prevent` modifier was not used, or the browser/system explicitly disallows preventing the default action for that specific shortcut.

fix

Ensure you've added the `.prevent` modifier to your event: `@keyup.ctrl.s.prevent="myHandler"`. If the issue persists, the shortcut is likely reserved by the browser/OS and cannot be overridden.

Upgrade

Version history

3.0.1latest on npm

Audit

Dependencies

vuerequiredPeer dependency, required for component functionality.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/shentao/vue-global-events ↗

packagehttps://www.npmjs.com/package/vue-global-events ↗