Vue 3 Click Away Directive

1.2.4 · active · verified Sun Apr 19

vue3-click-away is a Vue 3.x compatible directive designed to detect click events that occur outside of a specified element. It provides a simple mechanism for components to react when a user clicks anywhere on the document except on the element itself or its children. Currently at version 1.2.4, the package sees irregular but active maintenance, primarily addressing critical fixes such as recent server-side rendering (SSR) compatibility issues. Key differentiators include its explicit support for Vue 3's plugin system, direct directive registration, and a mixin option, offering flexibility in integration depending on the project's setup and preference. It ships with TypeScript types, facilitating its use in TypeScript-first Vue projects. Its primary goal is to abstract away the complexity of managing global click listeners for 'click away' scenarios.

Common errors

```
Failed to resolve directive: click-away
```
cause The `v-click-away` directive has not been registered globally or locally in the component.

fix Globally register the directive using `app.use(VueClickAway)` where `VueClickAway` is the default import. Alternatively, locally register it within your component's `directives` option: `import { directive } from 'vue3-click-away'; directives: { ClickAway: directive }`.
```
TypeError: Cannot read properties of undefined (reading 'use')
```
cause Attempting to use `VueClickAway` as a plugin on a non-Vue app instance, or `VueClickAway` was incorrectly imported (e.g., using named import for the plugin).

fix Ensure `VueClickAway` is imported as the default export (`import VueClickAway from 'vue3-click-away'`) and that `app.use()` is called on a valid Vue 3 application instance created with `createApp()`.
```
Error: Hydration completed but contains mismatches.
```
cause This usually indicates an issue where the server-rendered HTML differs from the client-rendered output, often related to directives or dynamic content, particularly in SSR environments with older versions of the package.

fix Update `vue3-click-away` to the latest version (1.2.4+). If the problem persists, consider wrapping the component using `v-click-away` in a `<ClientOnly>` component (if your SSR framework supports it) to ensure the directive is only active on the client-side.

Warnings

breaking The package transitioned from being solely a directive to also exporting a plugin in v1.1.0. While the directive export remains, the primary recommended usage shifted towards the plugin approach via `app.use()`. Direct registrations of the directive might need adjustments or ensure correct named import.
Fix: For global usage, import `VueClickAway` (default export) and use `app.use(VueClickAway)`. For local component registration, import `directive` (named export) and use `directives: { ClickAway: directive }`.
gotcha Early versions (prior to v1.2.3) had known issues with Server-Side Rendering (SSR) environments, potentially leading to hydration mismatches or errors. These were addressed in subsequent patches, but complex SSR setups might still require careful testing.
Fix: Ensure you are using version 1.2.4 or newer. If issues persist in SSR, review the SSR configuration of your Vue application and ensure `v-click-away` is appropriately handled or rendered only on the client-side where necessary.
gotcha When using the directive, the `v-click-away` handler function receives the native `MouseEvent` object as its argument. If your handler expects different parameters or uses an incorrect signature, it might lead to unexpected behavior.
Fix: Ensure your handler function is defined to accept a single argument, which will be the native `MouseEvent`. E.g., `onClickAway(event: MouseEvent) { /* ... */ }`.

Install

npm install vue3-click-away npm
yarn add vue3-click-away yarn
pnpm add vue3-click-away pnpm

Imports

VueClickAway
wrong:
```
import { VueClickAway } from 'vue3-click-away'
```
correct:
```
import VueClickAway from 'vue3-click-away'
```
This is the default export, primarily intended for global registration as a Vue plugin via `app.use()`.
directive
wrong:
```
import directive from 'vue3-click-away'
```
correct:
```
import { directive } from 'vue3-click-away'
```
Used for local registration of the click-away directive on a per-component basis in the `directives` option.
mixin
wrong:
```
import mixin from 'vue3-click-away'
```
correct:
```
import { mixin } from 'vue3-click-away'
```
Provides the click-away functionality as a Vue mixin for components that prefer the Options API mixin pattern.

Quickstart

This quickstart demonstrates the global registration of vue3-click-away as a Vue plugin and its basic usage within a component to detect clicks outside a specific element, incrementing a counter upon detection.

import { createApp } from 'vue';
import VueClickAway from 'vue3-click-away';

const App = {
  template: `
    <div style="padding: 20px; border: 1px solid #ccc;" v-click-away="onClickAway">
      Click inside me! ({{ clickCount }} clicks)
      <p>This box detects clicks outside itself.</p>
    </div>
    <button @click="resetCount">Reset Counter</button>
    <p>Click anywhere else on the page.</p>
  `,
  data() {
    return { clickCount: 0 };
  },
  methods: {
    onClickAway(event) {
      this.clickCount++;
      console.log('Clicked away!', event);
    },
    resetCount() {
      this.clickCount = 0;
    }
  }
};

const app = createApp(App);

app.use(VueClickAway); // Register the directive globally
app.mount('#app');

// To run this in a real HTML file, you would need a div with id="app":
// <div id="app"></div>

view raw JSON →