vue-use-intersection-observer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alberto Mateo Alcalá
+
+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,144 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/Mathiew82/vue-use-intersection-observer/main/logo.png" alt="vue-use-intersection-observer logo" width="300" />
+</div>
+
+<div align="center">
+
+![npm](https://img.shields.io/npm/v/vue-use-intersection-observer)
+![npm downloads](https://img.shields.io/npm/dw/vue-use-intersection-observer)
+![GitHub stars](https://img.shields.io/github/stars/Mathiew82/vue-use-intersection-observer)
+![GitHub forks](https://img.shields.io/github/forks/Mathiew82/vue-use-intersection-observer)
+[![License](https://img.shields.io/crates/l/rnr.svg)](https://github.com/Mathiew82/vue-use-intersection-observer/blob/master/LICENSE)
+
+</div>
+
+Simple and lightweight visibility observer for **vue 3**, built on top of `IntersectionObserver`.
+
+## ✨ Features
+
+- Vue 3 plugin
+- Composable API
+- Uses native `IntersectionObserver`
+- Supports offsets and reactivity
+- One global observer (better performance)
+- Fully written in typescript
+
+&nbsp;
+
+## 📦 Installation
+
+```bash
+npm i vue-use-intersection-observer
+```
+
+## 🚀 How to use
+
+### 🔌 Plugin setup
+
+main.ts
+
+```typescript
+import { createApp } from 'vue';
+import './style.css';
+import App from './App.vue';
+import { VisibilityPlugin } from 'vue-use-intersection-observer';
+
+const app = createApp(App);
+app.use(VisibilityPlugin);
+app.mount('#app');
+```
+
+### 🧩 Usage (example)
+
+In a component
+
+```vue
+<template>
+  <div
+    :style="{
+      position: 'fixed',
+      top: '20px',
+      right: '20px',
+      width: '40px',
+      height: '40px',
+      borderRadius: '50%',
+      backgroundColor: isvisible ? 'green' : 'red',
+    }"
+  />
+
+  <div style="height: 150vh" />
+
+  <div ref="target" style="width: 200px; height: 200px; background: gray">
+    Observed Element
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted, onBeforeUnmount } from 'vue';
+import { useIntersectionObserver } from 'vue-use-intersection-observer';
+
+const target = ref<HTMLElement | null>(null);
+const isvisible = ref(false);
+
+const { observe, unobserve } = useIntersectionObserver();
+
+onMounted(() => {
+  observe(target, {
+    once: false,
+    callback: (visible) => {
+      isvisible.value = visible;
+    },
+  });
+});
+
+onBeforeUnmount(() => {
+  unobserve(target);
+});
+</script>
+```
+
+### ▶️ Demo
+
+![Demo](https://raw.githubusercontent.com/Mathiew82/vue-use-intersection-observer/main/demo.gif)
+
+### 🛠 API
+
+#### `useIntersectionObserver()`
+
+Composable used to observe when elements enter or leave the viewport.
+
+```ts
+const { observe, unobserve } = useIntersectionObserver();
+```
+
+---
+
+#### `observe()`
+
+Start observing an element.
+
+**Parameters:**
+
+| Name    | Type    | Description            |
+| ------- | ------- | ---------------------- |
+| target  | ref     | Element ref to observe |
+| options | Options | Observer configuration |
+
+**Options:**
+
+| Option    | Type            | Description                      | Optional | Default |
+| --------- | --------------- | -------------------------------- | -------- | ------- |
+| callback  | function        | Called when visibility changes   | false    | —       |
+| offset    | number          | Trigger before entering viewport | true     | `0`     |
+| threshold | number or array | Intersection threshold           | true     | `0`     |
+| once      | boolean         | Trigger only the first time      | true     | `true`  |
+
+---
+
+#### `unobserve()`
+
+Stop observing a previously registered element.
+
+| Name   | Type | Description                   |
+| ------ | ---- | ----------------------------- |
+| target | ref  | Element ref to stop observing |

package/dist/composables/useIntersectionObserver.d.ts

@@ -0,0 +1,10 @@
+import { type Ref } from 'vue';
+import { type VisibilityOptions, type VisibilityCallback } from '../core/visibilityObserver';
+interface ObserveParams extends VisibilityOptions {
+    callback: VisibilityCallback;
+}
+export declare function useIntersectionObserver(): {
+    observe: (elementRef: Ref<HTMLElement | null>, options: ObserveParams) => void;
+    unobserve: (elementRef: Ref<HTMLElement | null>) => void;
+};
+export {};

package/dist/core/visibilityObserver.d.ts

@@ -0,0 +1,15 @@
+export interface VisibilityOptions {
+    offset?: number;
+    threshold?: number | number[];
+    once?: boolean;
+}
+export type VisibilityCallback = (isVisible: boolean, entry: IntersectionObserverEntry) => void;
+export declare class VisibilityObserver {
+    private buckets;
+    private buildRootMargin;
+    private getKey;
+    private getBucket;
+    observe(element: Element, callback: VisibilityCallback, options?: VisibilityOptions): void;
+    unobserve(element: Element): void;
+    disconnect(): void;
+}

package/dist/directives/vVisible.d.ts

@@ -0,0 +1,10 @@
+import type { DirectiveBinding } from 'vue';
+import { type VisibilityOptions, type VisibilityCallback } from '../core/visibilityObserver';
+interface DirectiveValue extends VisibilityOptions {
+    callback: VisibilityCallback;
+}
+export declare const vVisible: {
+    mounted(el: HTMLElement, binding: DirectiveBinding<DirectiveValue>): void;
+    unmounted(el: HTMLElement): void;
+};
+export {};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { VisibilityPlugin } from './plugin';
+export { useIntersectionObserver } from './composables/useIntersectionObserver';
+export type { VisibilityOptions } from './core/visibilityObserver';

package/dist/plugin.d.ts

@@ -0,0 +1,6 @@
+import type { InjectionKey, Plugin } from 'vue';
+import { VisibilityObserver, type VisibilityOptions } from './core/visibilityObserver';
+export declare const VisibilityObserverKey: InjectionKey<VisibilityObserver>;
+export interface VisibilityPluginOptions extends Omit<VisibilityOptions, 'once'> {
+}
+export declare const VisibilityPlugin: Plugin;

package/dist/vue-use-intersection-observer.es.js

@@ -0,0 +1,83 @@
+import { inject as k, onBeforeUnmount as f } from "vue";
+class u {
+  buckets = /* @__PURE__ */ new Map();
+  buildRootMargin(e = 0) {
+    return `0px 0px -${e}px 0px`;
+  }
+  getKey(e = 0, s = 0) {
+    const t = Array.isArray(s) ? s.join(",") : String(s);
+    return `${e}|${t}`;
+  }
+  getBucket(e = 0, s = 0) {
+    const t = this.getKey(e, s), n = this.buckets.get(t);
+    if (n) return n;
+    const o = {
+      elements: /* @__PURE__ */ new Map(),
+      observer: new IntersectionObserver(
+        (i) => {
+          for (const c of i) {
+            const b = o.elements.get(c.target);
+            if (!b) continue;
+            const l = c.isIntersecting;
+            b.callback(l, c), l && b.once && this.unobserve(c.target);
+          }
+        },
+        {
+          root: null,
+          rootMargin: this.buildRootMargin(e),
+          threshold: s
+        }
+      )
+    };
+    return this.buckets.set(t, o), o;
+  }
+  observe(e, s, t = {}) {
+    const n = t.offset ?? 0, o = t.threshold ?? 0, i = this.getBucket(n, o);
+    i.elements.set(e, {
+      callback: s,
+      once: t.once ?? !0
+    }), i.observer.observe(e);
+  }
+  unobserve(e) {
+    for (const [s, t] of this.buckets)
+      if (t.elements.has(e)) {
+        t.elements.delete(e), t.observer.unobserve(e), t.elements.size === 0 && (t.observer.disconnect(), this.buckets.delete(s));
+        return;
+      }
+  }
+  disconnect() {
+    for (const [, e] of this.buckets)
+      e.elements.clear(), e.observer.disconnect();
+    this.buckets.clear();
+  }
+}
+const v = new u(), g = {
+  mounted(r, e) {
+    v.observe(r, e.value.callback, e.value);
+  },
+  unmounted(r) {
+    v.unobserve(r);
+  }
+}, a = /* @__PURE__ */ Symbol("VisibilityObserver"), d = {
+  install(r) {
+    const e = new u();
+    r.provide(a, e), r.directive("visible", g);
+  }
+};
+function h() {
+  const r = k(a, null), e = r ?? new u(), s = (n, o) => {
+    n.value && e.observe(n.value, o.callback, o);
+  }, t = (n) => {
+    n.value && e.unobserve(n.value);
+  };
+  return f(() => {
+    r || e.disconnect();
+  }), {
+    observe: s,
+    unobserve: t
+  };
+}
+export {
+  d as VisibilityPlugin,
+  h as useIntersectionObserver
+};

package/dist/vue-use-intersection-observer.umd.js

@@ -0,0 +1 @@
+(function(r,c){typeof exports=="object"&&typeof module<"u"?c(exports,require("vue")):typeof define=="function"&&define.amd?define(["exports","vue"],c):(r=typeof globalThis<"u"?globalThis:r||self,c(r.VueVisibilityObserver={},r.Vue))})(this,(function(r,c){"use strict";class l{buckets=new Map;buildRootMargin(e=0){return`0px 0px -${e}px 0px`}getKey(e=0,s=0){const t=Array.isArray(s)?s.join(","):String(s);return`${e}|${t}`}getBucket(e=0,s=0){const t=this.getKey(e,s),i=this.buckets.get(t);if(i)return i;const o={elements:new Map,observer:new IntersectionObserver(u=>{for(const b of u){const v=o.elements.get(b.target);if(!v)continue;const d=b.isIntersecting;v.callback(d,b),d&&v.once&&this.unobserve(b.target)}},{root:null,rootMargin:this.buildRootMargin(e),threshold:s})};return this.buckets.set(t,o),o}observe(e,s,t={}){const i=t.offset??0,o=t.threshold??0,u=this.getBucket(i,o);u.elements.set(e,{callback:s,once:t.once??!0}),u.observer.observe(e)}unobserve(e){for(const[s,t]of this.buckets)if(t.elements.has(e)){t.elements.delete(e),t.observer.unobserve(e),t.elements.size===0&&(t.observer.disconnect(),this.buckets.delete(s));return}}disconnect(){for(const[,e]of this.buckets)e.elements.clear(),e.observer.disconnect();this.buckets.clear()}}const f=new l,y={mounted(n,e){f.observe(n,e.value.callback,e.value)},unmounted(n){f.unobserve(n)}},a=Symbol("VisibilityObserver"),k={install(n){const e=new l;n.provide(a,e),n.directive("visible",y)}};function g(){const n=c.inject(a,null),e=n??new l,s=(i,o)=>{i.value&&e.observe(i.value,o.callback,o)},t=i=>{i.value&&e.unobserve(i.value)};return c.onBeforeUnmount(()=>{n||e.disconnect()}),{observe:s,unobserve:t}}r.VisibilityPlugin=k,r.useIntersectionObserver=g,Object.defineProperty(r,Symbol.toStringTag,{value:"Module"})}));

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "vue-use-intersection-observer",
+  "version": "1.0.0",
+  "description": "Simple visibility observer plugin for Vue 3 using IntersectionObserver.",
+  "type": "module",
+  "main": "./dist/vue-use-intersection-observer.umd.js",
+  "module": "./dist/vue-use-intersection-observer.es.js",
+  "types": "./dist/index.d.ts",
+  "author": {
+    "name": "Alberto Mateo Alcalá",
+    "url": "https://amateo82.es"
+  },
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/vue-use-intersection-observer.es.js",
+      "require": "./dist/vue-use-intersection-observer.umd.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && tsc -p tsconfig.lib.json",
+    "preview": "vite preview",
+    "format": "prettier . --write"
+  },
+  "peerDependencies": {
+    "vue": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@vitejs/plugin-vue": "^6.0.1",
+    "@vue/tsconfig": "^0.8.1",
+    "prettier": "^3.7.4",
+    "typescript": "~5.9.3",
+    "vite": "^7.2.4",
+    "vue-tsc": "^3.1.4"
+  }
+}