v-click-outside Vue Directive

Common errors

• TypeError: Cannot read properties of undefined (reading 'directive')

  cause Attempting to access `vClickOutside.directive` when `vClickOutside` was imported as a named export or incorrectly.
  fix Ensure `vClickOutside` is imported as the default export: `import vClickOutside from 'v-click-outside';`.

• Vue error: Failed to resolve directive: click-outside

  cause The `v-click-outside` directive was not properly registered, either globally using `Vue.use()` or locally within the component's `directives` option.
  fix For global registration: `Vue.use(vClickOutside);` in your main app file. For local component registration: `directives: { clickOutside: vClickOutside.directive }` within your component options.

• The callback function receives 'undefined' instead of the event object.

  cause This error often occurs when the callback function expects a second argument (the element), which was removed in v3.0.0, or when the `v-click-outside` handler is passed incorrectly.
  fix Since v3.0.0, the handler function only receives the `event` object. Ensure your handler's signature is `myHandler(event)`.

Warnings

• breaking In v3.0.0, the `el` (element) argument was removed from the callback function passed to the directive. The callback now exclusively receives the native `event` object.
  Fix: Update your callback functions to only expect the `event` object as an argument. If access to the bound element is required, capture it through other means within your component's context (e.g., using `this.$refs`).
• gotcha The `v-click-outside` directive is explicitly designed *not* to stop event propagation. If your application logic relies on event propagation being halted, you might encounter unexpected behavior where events continue to bubble up the DOM.
  Fix: If specific scenarios require preventing further event propagation, manually call `event.stopPropagation()` within your directive's handler or middleware, or adjust your event listener design accordingly.
• gotcha The `middleware` function, if provided, must execute synchronously and return a boolean value (`true` to allow the handler to fire, `false` to prevent it). Asynchronous operations within the middleware will not effectively block the handler's execution.
  Fix: Ensure your `middleware` function performs only synchronous checks and consistently returns a boolean value to correctly control whether the main handler is invoked.
• gotcha An Internet Explorer 11 (IE11) specific fix implemented in `v3.1.2` added a check for `document.activeElement`. This change could potentially influence how certain focus-related events are handled, especially in older browser environments or in applications with complex focus management.
  Fix: If experiencing unexpected behavior with `v-click-outside` in IE11 or similar older browsers, particularly involving focus or element activation, review the interaction with `document.activeElement` and consider your application's focus management strategies.

Install

• npm install v-click-outside npm
• yarn add v-click-outside yarn
• pnpm add v-click-outside pnpm

Imports

• vClickOutside
  wrong:

  const vClickOutside = require('v-click-outside')

  correct:

  import vClickOutside from 'v-click-outside'

  CommonJS `require` syntax is typically not used in modern Vue projects, which favor ES Modules. This import is used for global registration via `Vue.use()`.
• directive (local registration)
  wrong:

  import { directive } from 'v-click-outside'; /* This works but is less common for local component registration */

  correct:

  import vClickOutside from 'v-click-outside'; /* then in component: directives: { clickOutside: vClickOutside.directive } */

  When registering the directive locally within a Vue component's `directives` option, access the `directive` property from the default export.
• { bind, unbind } (programmatic hooks)
  wrong:

  import vClickOutside from 'v-click-outside'; const { bind, unbind } = vClickOutside;

  correct:

  import { directive } from 'v-click-outside'; const { bind, unbind } = directive;

  For programmatic access to the directive's `bind` and `unbind` lifecycle hooks, destructure them directly from the `directive` export.

Quickstart

This quickstart demonstrates how to globally register and use the `v-click-outside` directive with advanced configuration options, including a handler function, a middleware for conditional execution, and custom event types like `click` and `touchstart`.

import Vue from 'vue';
import vClickOutside from 'v-click-outside';

// Globally register the directive
Vue.use(vClickOutside);

// Define a simple root Vue component
new Vue({
  el: '#app',
  data () {
    return {
      showMenu: false,
      vcoConfig: {
        handler: this.handleOutsideClickWithConfig,
        middleware: this.middleware,
        events: ['click', 'touchstart'], // Respond to both mouse and touch events
        isActive: true,
        detectIFrame: true,
        capture: false
      }
    }
  },
  methods: {
    toggleMenu() {
      this.showMenu = !this.showMenu;
      console.log('Menu toggled:', this.showMenu);
    },
    handleOutsideClickWithConfig (event) {
      if (this.showMenu) { // Only close if menu is open
        this.showMenu = false;
        console.log('Clicked outside (config handler). Event type:', event.type);
      }
    },
    // Middleware returns true to fire handler, false to prevent
    middleware (event) {
      // Example: Do not close if the click was on an element with class 'ignore-outside'
      const ignoreElement = event.target.closest('.ignore-outside');
      if (ignoreElement) {
        console.log('Middleware ignored click on element with class:', ignoreElement.className);
        return false;
      }
      return true; // Allow handler to fire
    }
  },
  template: `
    <div id="app-container" style="padding: 20px; border: 1px solid #ccc; font-family: sans-serif;">
      <h1>v-click-outside Demo</h1>
      <button @click="toggleMenu" style="padding: 8px 15px; background-color: #007bff; color: white; border: none; border-radius: 4px; cursor: pointer;">Toggle Menu</button>

      <div v-if="showMenu"
           v-click-outside="vcoConfig"
           style="background: #e0e0e0; border: 1px solid #999; padding: 10px; margin-top: 10px; width: 200px; box-shadow: 2px 2px 8px rgba(0,0,0,0.2);">
        <h2 style="margin-top: 0; font-size: 1.2em;">My Menu</h2>
        <ul style="list-style: none; padding: 0;">
          <li style="margin-bottom: 5px;">Item 1</li>
          <li style="margin-bottom: 5px;">Item 2</li>
        </ul>
        <button class="ignore-outside" style="padding: 5px 10px; background-color: #6c757d; color: white; border: none; border-radius: 3px; cursor: pointer;">Don't close me</button>
      </div>

      <div style="margin-top: 30px; padding: 10px; border: 1px dashed grey; background-color: #f8f9fa;">
        Click here or anywhere outside the menu to see the directive in action.
        <p class="ignore-outside" style="margin-top: 10px; font-style: italic; color: #555;">This text is inside an element with class 'ignore-outside' and clicks here will be ignored by the middleware.</p>
      </div>
    </div>
  `
});