Vue ClickOutside Directive

1.1.0 · abandoned · verified Sun Apr 19

This package provides a simple Vue.js directive, `v-click-outside`, designed to detect clicks that occur outside of the element it is bound to. Primarily developed for Vue 2, the package (version 1.1.0) was last published over six years ago, indicating it is no longer actively maintained. Its straightforward implementation allows developers to easily create components like dropdowns or modals that close when a user clicks anywhere outside their boundaries. Due to its age, it does not support Vue 3's directive API changes or Composition API patterns. For modern Vue 3 projects, developers should consider updated alternatives like `@vueuse/core`'s `onClickOutside` composable or `v-click-outside` from other maintainers that have been updated for Vue 3.

Common errors

```
Failed to resolve directive: click-outside
```
cause The `v-click-outside` directive was not properly registered or imported into the Vue component or application. This is common when using local component registration without including it in the `directives` option.

fix Ensure that `ClickOutside` is imported from 'vue-click-outside' and explicitly listed in the `directives` option of your Vue component, e.g., `directives: { ClickOutside }`.
```
TypeError: Cannot read properties of undefined (reading 'handler') or similar errors related to directive configuration in Vue 3.
```
cause This package uses Vue 2's directive API, which is incompatible with Vue 3's API changes. Vue 3 directives use different hook names and a slightly different structure.

fix This package is not compatible with Vue 3. You must use a Vue 3-compatible click-outside solution. This includes using a dedicated Vue 3 library or implementing a custom directive/composable designed for Vue 3.

Warnings

breaking This `vue-click-outside` package (version 1.1.0) is fundamentally incompatible with Vue 3. Vue 3 introduced significant changes to custom directive lifecycle hooks (e.g., `bind` became `beforeMount`, `unbind` became `unmounted`). Attempts to use this package in a Vue 3 project will result in runtime errors.
Fix: For Vue 3, use a modern alternative such as `@vueuse/core`'s `onClickOutside` composable or `vOnClickOutside` directive, `v-click-outside` by ndelvalle (which has Vue 3 support), or implement a custom click-outside directive using Vue 3's Composition API.
deprecated The package has not been updated in over six years and is considered abandoned. There are numerous modern, actively maintained alternatives that offer better compatibility with current Vue versions (especially Vue 3) and often include more robust features like handling iframes or dynamic content.
Fix: Migrate to a contemporary `click-outside` solution built for modern Vue, such as `@vueuse/core` or other dedicated Vue 3 directives/composables.
gotcha When an element is opened by a click event, the `v-click-outside` directive might immediately trigger its 'hide' handler if the opening click event is not properly stopped. This happens because the click event bubbles up to the document, where the click-outside listener is typically attached, before the element is fully 'visible' and recognized as the target.
Fix: Ensure the click event that *opens* the element has event propagation stopped. For example, use `@click.stop` on the button or element that toggles the visibility of the element with `v-click-outside`.
gotcha The example provided in the README uses `this.popupItem = this.$el` in `mounted()` to prevent the directive from triggering if the initial click was on the element itself. Forgetting or incorrectly implementing this pattern can lead to unexpected behavior where clicking the element to 'open' it immediately triggers the 'click outside' logic and closes it.
Fix: If adapting this directive manually, ensure that the element triggering the 'outside' event is not the same as the element itself or its children, typically by checking `event.target` against the element and its `contains` method, or by explicitly setting an ignored element reference as shown in the package's `mounted` hook.

Install

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

Imports

ClickOutside
wrong:
```
const ClickOutside = require('vue-click-outside')
```
correct:
```
import ClickOutside from 'vue-click-outside'
```
For local component registration, import the directive and register it in the `directives` option. This package primarily supports Vue 2.

Quickstart

Demonstrates how to import and locally register the `v-click-outside` directive to create a toggleable popup that closes when clicking anywhere outside of it. This example is for Vue 2 applications.

<template>
  <div>
    <button v-click-outside="hide" @click="toggle">Toggle Popup</button>
    <div v-show="opened" class="popup-content">
      This is a popup item. Click outside to close.
    </div>
  </div>
</template>

<script>
import ClickOutside from 'vue-click-outside'

export default {
  data () {
    return {
      opened: false
    }
  },

  methods: {
    toggle () {
      this.opened = !this.opened
    },

    hide () {
      // Only close if it's currently open
      if (this.opened) {
        this.opened = false
      }
    }
  },

  mounted () {
    // Important: Prevent click outside event from being triggered by a click
    // on the element itself when using 'popupItem' for detection.
    // In this specific implementation, it uses $el to bind to the root element.
    this.popupItem = this.$el
  },

  // Don't forget to register the directive locally
  directives: {
    ClickOutside
  }
}
</script>

<style scoped>
.popup-content {
  border: 1px solid #ccc;
  padding: 20px;
  background-color: white;
  margin-top: 10px;
}
</style>

view raw JSON →