vue3-click-outside-directive 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,237 @@
+# v-click-outside
+
+> Vue 3 directive that fires when a click is registered outside of an element.  
+> TypeScript-first · Zero dependencies · Shadow DOM ready · SSR safe
+
+[![npm version](https://img.shields.io/npm/v/v-click-outside)](https://npmjs.com/package/v-click-outside)
+[![license](https://img.shields.io/npm/l/v-click-outside)](./LICENSE)
+
+---
+
+## Installation
+
+```bash
+npm install v-click-outside
+# or
+pnpm add v-click-outside
+# or
+yarn add v-click-outside
+```
+
+---
+
+## Vue 3
+
+### Global registration
+
+Register the plugin once in `main.ts` — the directive becomes available in every component.
+
+```ts
+// main.ts
+import { createApp } from "vue";
+import { ClickOutsidePlugin } from "v-click-outside";
+import App from "./App.vue";
+
+const app = createApp(App);
+app.use(ClickOutsidePlugin);
+app.mount("#app");
+```
+
+```vue
+<template>
+  <div v-click-outside="onClickOutside">...</div>
+</template>
+
+<script setup lang="ts">
+function onClickOutside(event: PointerEvent) {
+  console.log("clicked outside", event);
+}
+</script>
+```
+
+### Local registration
+
+Import the directive directly in the component — no global setup needed.
+
+```vue
+<script setup lang="ts">
+import { vClickOutside } from "v-click-outside";
+
+function onClickOutside(event: PointerEvent) {
+  console.log("clicked outside", event);
+}
+</script>
+
+<template>
+  <div v-click-outside="onClickOutside">...</div>
+</template>
+```
+
+### TypeScript — global directive types
+
+When using global registration, add a type declaration so the template gets proper type checking:
+
+```ts
+// src/types/directives.d.ts
+import type { Directive } from "vue";
+import type { ClickOutsideHandler, ClickOutsideOptions } from "v-click-outside";
+
+declare module "vue" {
+  interface GlobalDirectives {
+    vClickOutside: Directive<
+      HTMLElement,
+      ClickOutsideHandler | ClickOutsideOptions
+    >;
+  }
+}
+```
+
+---
+
+## Nuxt 3 / Nuxt 4
+
+### Plugin
+
+Create a plugin file — Nuxt picks it up automatically, no manual registration needed.
+
+```ts
+// plugins/v-click-outside.ts
+import { ClickOutsidePlugin } from "v-click-outside";
+
+export default defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.vueApp.use(ClickOutsidePlugin);
+});
+```
+
+### TypeScript — global directive types
+
+```ts
+// types/directives.d.ts
+import type { Directive } from "vue";
+import type { ClickOutsideHandler, ClickOutsideOptions } from "v-click-outside";
+
+declare module "vue" {
+  interface GlobalDirectives {
+    vClickOutside: Directive<
+      HTMLElement,
+      ClickOutsideHandler | ClickOutsideOptions
+    >;
+  }
+}
+```
+
+### SSR
+
+The directive is SSR-safe — it registers the `pointerdown` listener only in `mounted`, which runs exclusively on the client.
+
+---
+
+## API
+
+### Simple — pass a handler function
+
+```vue
+<div v-click-outside="handler" />
+```
+
+```ts
+function handler(event: PointerEvent) {
+  console.log("clicked outside", event);
+}
+```
+
+### Advanced — pass an options object
+
+```vue
+<div v-click-outside="{ handler, ignore: [triggerEl], disabled: isDisabled }" />
+```
+
+| Option     | Type                                      | Default | Description                                            |
+| ---------- | ----------------------------------------- | ------- | ------------------------------------------------------ |
+| `handler`  | `(e: PointerEvent) => void`               | —       | **Required.** Called when a click outside is detected  |
+| `ignore`   | `Array<HTMLElement \| null \| undefined>` | `[]`    | Elements whose clicks are treated as "inside"          |
+| `disabled` | `boolean`                                 | `false` | Disable the directive without removing it from the DOM |
+
+---
+
+## Examples
+
+### Dropdown menu
+
+The most common use case. The `ignore` option prevents the trigger button from immediately closing the menu it just opened.
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+
+const open = ref(false);
+const triggerRef = ref<HTMLElement>();
+
+function close() {
+  open.value = false;
+}
+</script>
+
+<template>
+  <button ref="triggerRef" @click="open = !open">Menu</button>
+
+  <ul v-if="open" v-click-outside="{ handler: close, ignore: [triggerRef] }">
+    <li>Item 1</li>
+    <li>Item 2</li>
+  </ul>
+</template>
+```
+
+> **Why `ignore: [triggerRef]`?**  
+> Without it, clicking the button fires `@click` (opens the menu) and `v-click-outside` simultaneously (closes it), because the button is outside the `<ul>`. Adding it to `ignore` breaks the cycle.
+
+### Modal / dialog
+
+```vue
+<script setup lang="ts">
+const props = defineProps<{ modelValue: boolean }>();
+const emit = defineEmits<{ "update:modelValue": [value: boolean] }>();
+</script>
+
+<template>
+  <div v-if="modelValue" class="overlay">
+    <div
+      v-click-outside="() => emit('update:modelValue', false)"
+      class="dialog"
+    >
+      <slot />
+    </div>
+  </div>
+</template>
+```
+
+### Conditionally disable
+
+```vue
+<template>
+  <div
+    v-click-outside="{
+      handler: onClickOutside,
+      disabled: !isEditing,
+    }"
+  >
+    ...
+  </div>
+</template>
+```
+
+---
+
+## How it works
+
+- Listens to `pointerdown` on `document` — fires before `click` and works for touch events
+- Uses `event.composedPath()` for correct Shadow DOM support, falls back to `event.target`
+- The listener is created once in `mounted` and removed in `unmounted` — no leaks
+- On `updated`, options are swapped in-place without recreating the listener
+- `null` / `undefined` entries in `ignore` are safely skipped
+
+---
+
+## License
+
+MIT

package/dist/directive.d.ts

@@ -0,0 +1,10 @@
+import { ObjectDirective } from 'vue';
+import { ClickOutsideOptions } from './types';
+export type { ClickOutsideHandler, ClickOutsideOptions } from './types';
+interface ClickOutsideEl extends HTMLElement {
+    _clickOutside?: {
+        options: Required<ClickOutsideOptions>;
+        listener: (e: PointerEvent) => void;
+    };
+}
+export declare const vClickOutside: ObjectDirective<ClickOutsideEl>;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { vClickOutside } from './directive';
+export { ClickOutsidePlugin } from './plugin';
+export type { ClickOutsideHandler, ClickOutsideOptions } from './types';

package/dist/plugin.d.ts

@@ -0,0 +1,4 @@
+import { App } from 'vue';
+export declare const ClickOutsidePlugin: {
+    install(app: App): void;
+};

package/dist/types.d.ts

@@ -0,0 +1,15 @@
+export type ClickOutsideHandler = (event: PointerEvent) => void;
+export interface ClickOutsideOptions {
+    /** Handler called when a click outside the element is detected */
+    handler: ClickOutsideHandler;
+    /**
+     * List of extra elements to treat as "inside".
+     * Clicks on these elements will NOT trigger the handler.
+     */
+    ignore?: Array<HTMLElement | null | undefined>;
+    /**
+     * If true, the directive is disabled and won't react to clicks.
+     * @default false
+     */
+    disabled?: boolean;
+}

package/dist/v-click-outside.es.js

@@ -0,0 +1,44 @@
+//#region src/directive.ts
+function e(e) {
+	if (typeof e.value == "function") return {
+		handler: e.value,
+		ignore: [],
+		disabled: !1
+	};
+	if (e.value !== null && typeof e.value == "object" && typeof e.value.handler == "function") return {
+		handler: e.value.handler,
+		ignore: e.value.ignore ?? [],
+		disabled: e.value.disabled ?? !1
+	};
+	throw TypeError("[v-click-outside] value must be a Function or { handler: Function, ignore?: HTMLElement[], disabled?: boolean }");
+}
+function t(e) {
+	return e.composedPath()[0] ?? null;
+}
+function n(e) {
+	return (n) => {
+		let r = e._clickOutside;
+		if (!r || r.options.disabled) return;
+		let i = t(n);
+		i && (e === i || e.contains(i) || r.options.ignore.some((e) => e != null && (e === i || e.contains(i))) || r.options.handler(n));
+	};
+}
+var r = {
+	mounted(t, r) {
+		let i = e(r), a = n(t);
+		t._clickOutside = {
+			options: i,
+			listener: a
+		}, document.addEventListener("pointerdown", a, { passive: !0 });
+	},
+	updated(t, n) {
+		t._clickOutside && (t._clickOutside.options = e(n));
+	},
+	unmounted(e) {
+		e._clickOutside && (document.removeEventListener("pointerdown", e._clickOutside.listener), delete e._clickOutside);
+	}
+}, i = { install(e) {
+	e.directive("click-outside", r);
+} };
+//#endregion
+export { i as ClickOutsidePlugin, r as vClickOutside };

package/dist/v-click-outside.umd.js

@@ -0,0 +1 @@
+(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports):typeof define==`function`&&define.amd?define([`exports`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e.VClickOutside={}))})(this,function(e){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});function t(e){if(typeof e.value==`function`)return{handler:e.value,ignore:[],disabled:!1};if(e.value!==null&&typeof e.value==`object`&&typeof e.value.handler==`function`)return{handler:e.value.handler,ignore:e.value.ignore??[],disabled:e.value.disabled??!1};throw TypeError(`[v-click-outside] value must be a Function or { handler: Function, ignore?: HTMLElement[], disabled?: boolean }`)}function n(e){return e.composedPath()[0]??null}function r(e){return t=>{let r=e._clickOutside;if(!r||r.options.disabled)return;let i=n(t);i&&(e===i||e.contains(i)||r.options.ignore.some(e=>e!=null&&(e===i||e.contains(i)))||r.options.handler(t))}}var i={mounted(e,n){let i=t(n),a=r(e);e._clickOutside={options:i,listener:a},document.addEventListener(`pointerdown`,a,{passive:!0})},updated(e,n){e._clickOutside&&(e._clickOutside.options=t(n))},unmounted(e){e._clickOutside&&(document.removeEventListener(`pointerdown`,e._clickOutside.listener),delete e._clickOutside)}};e.ClickOutsidePlugin={install(e){e.directive(`click-outside`,i)}},e.vClickOutside=i});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "vue3-click-outside-directive",
+  "version": "1.0.0",
+  "description": "Vue 3 directive that fires when a click is registered outside the element",
+  "type": "module",
+  "main": "./dist/v-click-outside.umd.js",
+  "module": "./dist/v-click-outside.es.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/v-click-outside.es.js",
+      "require": "./dist/v-click-outside.umd.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "vue",
+    "vue3",
+    "directive",
+    "click-outside",
+    "nuxt"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "vue": "^3.0.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.5",
+    "@vue/test-utils": "^2.4.10",
+    "happy-dom": "^20.9.0",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.11",
+    "vite-plugin-dts": "^5.0.0",
+    "vitest": "^4.1.5",
+    "vue": "^3.5.34"
+  }
+}