{"id":12485,"library":"vue-global-events","title":"Vue Global Events","description":"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.","status":"active","version":"3.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/shentao/vue-global-events","tags":["javascript","vue","events","global","window","document","shortcuts","anywhere","listeners","typescript"],"install":[{"cmd":"npm install vue-global-events","lang":"bash","label":"npm"},{"cmd":"yarn add vue-global-events","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-global-events","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, required for component functionality.","package":"vue","optional":false}],"imports":[{"note":"The library primarily uses ES Modules. For Vue 3, ESM is the standard import method.","wrong":"const { GlobalEvents } = require('vue-global-events')","symbol":"GlobalEvents","correct":"import { GlobalEvents } from 'vue-global-events'"},{"note":"Registering the component globally allows its use without explicit local imports in every component where it's needed.","symbol":"GlobalEvents (global registration)","correct":"import { createApp } from 'vue'; import { GlobalEvents } from 'vue-global-events'; const app = createApp(...); app.component('GlobalEvents', GlobalEvents);"}],"quickstart":{"code":"import { createApp, ref } from 'vue';\nimport { GlobalEvents } from 'vue-global-events';\n\nconst App = {\n components: { GlobalEvents },\n setup() {\n const message = ref('Press Ctrl+Space to toggle, or Alt+S for a message.');\n const showGlobalEvents = ref(true);\n\n const toggleEvents = () => {\n showGlobalEvents.value = !showGlobalEvents.value;\n message.value = `Global events are now ${showGlobalEvents.value ? 'enabled' : 'disabled'}.`;\n };\n\n const showAltSMessage = () => {\n alert('Alt+S was pressed globally!');\n message.value = 'Alt+S was pressed!';\n };\n\n return {\n message,\n showGlobalEvents,\n toggleEvents,\n showAltSMessage,\n };\n },\n template: `\n
\n

Vue Global Events Demo

\n

{{ message }}

\n \n \n message = 'Page Down was pressed!'\"\n />\n \n
\n \n
\n
\n `\n};\n\ncreateApp(App).mount('#app');","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"Version 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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"Certain 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add `.prevent` to your event listener: `@keyup.ctrl.space.prevent=\"myHandler\"`.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Prefer 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `app.component('GlobalEvents', GlobalEvents)` is called for global registration, or include `GlobalEvents` in the `components` option of your consuming Vue component.","cause":"The `GlobalEvents` component was not registered with the Vue application (either globally or locally within the component where it's used).","error":"TypeError: Cannot read properties of undefined (reading 'component') or 'GlobalEvents' is not defined"},{"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.","cause":"The `filter` prop is preventing the event handler from executing, or the event target is not what's expected.","error":"Global event not firing when expected, or firing when it shouldn't (e.g., in an input field)."},{"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.","cause":"The `.prevent` modifier was not used, or the browser/system explicitly disallows preventing the default action for that specific shortcut.","error":"Browser default action (e.g., scrolling, tab switching) still occurs despite adding a global event listener."}],"ecosystem":"npm"}