Vue Global Events

Common errors

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

  cause 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).

  cause 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.

  cause 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.

Warnings

• breaking 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.
  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`.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Add `.prevent` to your event listener: `@keyup.ctrl.space.prevent="myHandler"`.
• gotcha 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.
  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.

Install

• npm install vue-global-events npm
• yarn add vue-global-events yarn
• pnpm add vue-global-events pnpm

Imports

• GlobalEvents
  wrong:

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

  correct:

  import { GlobalEvents } from '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.

Quickstart

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');