Vue Click Outside Element Directive

3.1.2 · active · verified Wed Apr 22

Vue-Click-Outside-Element is a specialized Vue directive designed to detect clicks that occur outside the DOM element it is applied to, rather than outside a Vue component. This distinction is crucial for scenarios where event delegation needs to target a specific HTML element. The current stable version is 3.1.2, which offers improved TypeScript typings and better testing, particularly for Vue 3. The package has seen recent updates, including a transition to Vite for building (v3.1.0) and significant refactoring for Vue 3 compatibility (v3.0.0). It is maintained with a clear roadmap, including plans to potentially combine element and component click-outside functionalities in the future. It's a lightweight solution focused solely on element-level click detection, differentiating it from more generalized event handling libraries or those specifically for component-level interaction.

Common errors

```
Error: You need to provide a function for v-click-outside-element directive
```
cause The directive was applied with a value that is not a function, e.g., a string, a boolean, or an undefined variable.

fix Ensure the value passed to `v-click-outside-element` is a reference to a valid method defined in your component's `methods` option, like `v-click-outside-element="myMethod"`.
```
Failed to resolve directive: click-outside-element
```
cause The directive has not been correctly registered with the Vue application instance.

fix Make sure you have called `app.use(vueClickOutsideElement)` after importing the plugin in your `main.js` or equivalent entry file for your Vue 3 application.
```
TypeError: app.use is not a function
```
cause Attempting to use `app.use()` on a non-Vue 3 application instance or incorrectly importing `createApp`.

fix Confirm you are working within a Vue 3 project structure and `createApp` is correctly imported from 'vue'. For Vue 2 projects, you should use `Vue.use(vueClickOutsideElement)` instead (after installing the Vue 2 compatible version).

Warnings

breaking Version 3.0.0 introduced breaking changes for Vue 3 compatibility. Directive hook methods changed from `bind` to `beforeMount` and `unbind` to `beforeUnmount`. Ensure your application is using Vue 3 when upgrading to `vue-click-outside-element@3.x.x`.
Fix: For Vue 3 projects, use `npm i vue-click-outside-element`. For Vue 2, explicitly install `npm i vue-click-outside-element@1.0.15`.
gotcha This directive is specifically designed for detecting clicks outside an *element*, not a *component*. If you need to detect clicks outside an entire Vue component, you should use a different package like `Vue-Click-Outside-Component` (from the same author) or implement a custom solution that targets the component's root element.
Fix: Verify whether you intend to detect clicks outside a specific HTML element or an entire Vue component. If the latter, consider `Vue-Click-Outside-Component` or adjust your implementation accordingly.
gotcha The directive `v-click-outside-element` expects a function reference from the component's `methods` object. Providing an inline function or an expression that doesn't resolve to a method will result in an error.
Fix: Always pass a reference to a method defined in your Vue component's `methods` option, e.g., `<div v-click-outside-element="myMethod"></div>`.
breaking The internal `clickOutside` function was re-done in version 3.1.0 to take `this` as an argument instead of relying on `element.clickOutside` to be present. While this is primarily an internal refactor, it signifies architectural changes that may affect highly customized usages.
Fix: No direct user-level fix is typically required unless you were relying on deeply internal implementation details. Ensure you are using the public API as documented.

Install

npm install vue-click-outside-element npm
yarn add vue-click-outside-element yarn
pnpm add vue-click-outside-element pnpm

Imports

vueClickOutsideElement
wrong:
```
import { vueClickOutsideElement } from 'vue-click-outside-element'
```
correct:
```
import vueClickOutsideElement from 'vue-click-outside-element'
```
The directive is exported as a default export for direct import and use with `app.use()` in Vue 3 applications.
Directive registration
wrong:
```
app.directive('click-outside-element', vueClickOutsideElement)
```
correct:
```
app.use(vueClickOutsideElement)
```
Register the plugin globally via `app.use()`. The default directive name is `click-outside-element`, but it can be customized as a second argument to `app.use()`.
TypeScript Type
```
import type { App } from 'vue'
```
While the package ships its own types, you might import `App` or other Vue types for type-checking your Vue application setup. The directive itself is typed for usage.

Quickstart

This quickstart demonstrates how to install and register the `v-click-outside-element` directive globally, then apply it to a button. Clicking anywhere outside the button will trigger the `closeButton` method, hiding the button. A secondary button allows you to bring the original button back into view.

import { createApp } from 'vue';
import vueClickOutsideElement from 'vue-click-outside-element';

// App.vue (within a single file component or separate)
const App = {
  template: `
    <div id="app">
      <button v-click-outside-element="closeButton" v-if="showButton" style="padding: 10px; background-color: lightblue;">Click outside me to hide</button>
      <p v-else>Button is hidden. Click anywhere to reset.</p>
      <button @click="showButton = true" v-if="!showButton" style="margin-top: 20px;">Show Button Again</button>
    </div>
  `,
  data() {
    return { showButton: true };
  },
  methods: {
    closeButton(event) {
      console.log('Clicked outside the button!', event.target);
      this.showButton = false;
    }
  }
};

const app = createApp(App);
app.use(vueClickOutsideElement);
app.mount('#app');

view raw JSON →