Wondering what’s next for npm?Check out our public roadmap! »

    vue-global-events

    1.2.1 • Public • Published

    vue-global-events Build Status npm package coverage

    Add shortcuts by listening to events on the document, anywhere

    Sponsors

    Bronze

    Vue Mastery logo Vue Jobs logo

    Installation

    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 unregistration either. You can toggle the events with a single v-if. Works with SSR too.

    Usage

    import GlobalEvents from 'vue-global-events'
     
    // register globally
    Vue.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

    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 to GlobalEvents component
    • eventName: event name with key modifiers

    filter should return false to prevent the execution of a handler:

    <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. eventName can contain key modifiers if used

    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" />

    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 includes Ctrl+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.
    • You can add custom keyCodes to Vue.config.keyCodes. This is especially useful for numbers on the digit row: add Vue.config.keyCodes.digit1 = 49 so you can write @keydown.digit1 because writing @keydown.1 will trigger when keyCode === 1.
    • About using keyup with modifiers like .ctrl or .shift: the keyup event is triggered when a key is released and that's also when the event.ctrlKey is checked, which if you just released, will be false. This is because ctrl, shift and alt are checked differently. If you want to trigger on the keyup event of a modifier, you need to use its keycode (check it here. For example, for the ctrl 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:

    npm run dev

    Demo

    Build the library with:

    npm run build

    And then open the index.html file

    Authors

    Damian Dulisz @shentao

    Eduardo San Martin Morote @posva

    License

    MIT

    Install

    npm i vue-global-events

    DownloadsWeekly Downloads

    10,004

    Version

    1.2.1

    License

    MIT

    Unpacked Size

    18.1 kB

    Total Files

    10

    Last publish

    Collaborators

    • avatar
    • avatar