InView: Detect Element Visibility in the Viewport

InView is a lightweight, high-performance JavaScript library for detecting when elements enter or exit the viewport. Perfect for lazy loading, scroll-triggered animations, infinite scrolling, and more.

🚀 Features

• Simple API: Intuitive and flexible configuration
• TypeScript Support: Complete type definitions included
• Vue.js Integration: Custom directives for seamless usage
• High Performance: Minimal overhead, efficient observation
• Customizable: Precision, delay, and single/multi-element support
• Modern Browser Support: Built on Intersection Observer API

📚 Table of Contents

• Installation
• Quick Start
• API Reference
  • Constructor
  • InViewConfig Interface
  • Methods
  • InViewEvent Object
• Examples
  • Basic Usage
  • Advanced Configuration
  • TypeScript Example
  • Vue.js Integration
• Browser Support
• License
• Author
• References

📦 Installation

Install via your preferred package manager:

npm install @opuu/inview
# or
pnpm install @opuu/inview
# or
yarn add @opuu/inview

Or use via CDN:

<script type="module">
    import InView from "https://cdn.jsdelivr.net/npm/@opuu/inview/dist/inview.js";
</script>

⚡ Quick Start

Import

For module bundlers (webpack, rollup, parcel, etc.):

import InView from "@opuu/inview";

For browsers with ES module support:

<script type="module">
    import InView from "node_modules/@opuu/inview/dist/inview.js";
</script>

Or use the CDN snippet above.

🛠️ API Reference

Constructor

Create a new InView instance by passing a CSS selector or a configuration object:

const inview = new InView(selectorOrConfig);

• selectorOrConfig: string (CSS selector) or InViewConfig object

InViewConfig Interface

Configure observation with the following options:

interface InViewConfig {
    selector: string;
    delay?: number;
    precision?: "low" | "medium" | "high";
    single?: boolean;
}

Methods

on(event, callback)

Listen for "enter" or "exit" events:

inview.on("enter", (event) => {
    // Element entered viewport
});
inview.on("exit", (event) => {
    // Element exited viewport
});

• event: "enter" or "exit"
• callback: (event: InViewEvent) => void

pause()

Pause observation:

inview.pause();

resume()

Resume observation:

inview.resume();

setDelay(delay)

Set callback delay (in ms):

inview.setDelay(200);

InViewEvent Object

The callback for "enter" and "exit" receives an InViewEvent object:

interface InViewEvent {
    percentage: number;
    rootBounds: DOMRectReadOnly | null;
    boundingClientRect: DOMRectReadOnly;
    intersectionRect: DOMRectReadOnly;
    target: Element;
    time: number;
    event: "enter" | "exit";
}

🧑‍💻 Examples

Basic Usage

Observe Elements by Selector

const elements = new InView(".css-selector");

elements.on("enter", (event) => {
    // Element entered viewport
});

elements.on("exit", (event) => {
    // Element exited viewport
});

Advanced Configuration

const element = new InView({
    selector: ".css-selector",
    delay: 100, // ms delay before callback
    precision: "high", // "low" | "medium" | "high"
    single: true, // Observe only the first match
});

TypeScript Example

import InView from "@opuu/inview";
import type { InViewConfig, InViewEvent } from "@opuu/inview";

const config: InViewConfig = {
    selector: ".css-selector",
    delay: 0,
    precision: "medium",
    single: true,
};

const element: InView = new InView(config);

element.on("enter", (event: InViewEvent) => {
    // Handle enter event
});

Vue.js Integration

InView provides Vue directives for easy integration.

Register Directives Globally

import { createInViewDirective, createOutViewDirective } from "@opuu/inview/vue";
const app = createApp(App);

app.directive("inview", createInViewDirective({ delay: 100, precision: "high", single: true }));
app.directive("outview", createOutViewDirective());

Usage in Templates

<template>
    <div v-inview="onEnterHandler" v-outview="onExitHandler">
        <!-- Content -->
    </div>
</template>

You can also register directives locally within a component.

🌐 Browser Support

InView uses the Intersection Observer API, supported by all modern browsers.
See browser compatibility.

📄 License

MIT License

👤 Author

Obaydur Rahman

🔗 References

• Intersection Observer API (MDN)
• Browser Support: caniuse.com