universal-virtual-scroll 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tejas Patil
+
+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,448 @@
+# universal-virtual-scroll
+
+A lightweight and framework-agnostic virtual scrolling library for efficiently rendering large lists and grids with smooth performance.
+
+---
+
+## Installation
+
+```bash
+npm install universal-virtual-scroll
+```
+
+---
+
+## Import
+
+```js
+import {
+  UniversalVirtualScroll
+} from 'universal-virtual-scroll';
+```
+
+---
+
+# Angular Example
+
+## app.component.html
+
+```html
+<div #viewport class="viewport">
+
+  <div
+    #content
+    [style.paddingTop.px]="paddingTop"
+    [style.paddingBottom.px]="paddingBottom">
+
+    @for (item of visibleItems; track item.name) {
+
+      <div class="card">
+
+        {{ item.name }}
+
+      </div>
+
+    }
+
+  </div>
+
+</div>
+```
+
+---
+
+## app.component.ts
+
+```ts
+import {
+  AfterViewInit,
+  Component,
+  ElementRef,
+  ViewChild
+} from '@angular/core';
+
+import {
+  UniversalVirtualScroll
+} from 'universal-virtual-scroll';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  templateUrl: './app.component.html',
+  styleUrl: './app.component.css'
+})
+export class AppComponent
+implements AfterViewInit {
+
+  @ViewChild('viewport')
+  viewport!: ElementRef;
+
+  @ViewChild('content')
+  content!: ElementRef;
+
+  visibleItems: any[] = [];
+
+  paddingTop = 0;
+
+  paddingBottom = 0;
+
+  items = Array.from(
+    { length: 100000 },
+    (_, i) => ({
+      name: `Item ${i + 1}`
+    })
+  );
+
+  ngAfterViewInit(): void {
+
+    new UniversalVirtualScroll({
+
+      viewport:
+        this.viewport.nativeElement,
+
+      content:
+        this.content.nativeElement,
+
+      items: this.items,
+
+      itemHeight: 100,
+
+      itemWidth: 200,
+
+      onUpdate: (
+        items,
+        top,
+        bottom
+      ) => {
+
+        this.visibleItems = items;
+
+        this.paddingTop = top;
+
+        this.paddingBottom = bottom;
+      }
+    });
+  }
+}
+```
+
+---
+
+## app.component.css
+
+```css
+.viewport {
+  height: 100vh;
+  overflow-y: auto;
+}
+
+.card {
+  height: 100px;
+}
+```
+
+---
+
+# React Example
+
+## App.jsx
+
+```jsx
+import {
+  useEffect,
+  useRef,
+  useState
+} from 'react';
+
+import {
+  UniversalVirtualScroll
+} from 'universal-virtual-scroll';
+
+function App() {
+
+  const viewportRef = useRef(null);
+
+  const contentRef = useRef(null);
+
+  const [visibleItems, setVisibleItems] =
+    useState([]);
+
+  const [paddingTop, setPaddingTop] =
+    useState(0);
+
+  const [paddingBottom, setPaddingBottom] =
+    useState(0);
+
+  const items = Array.from(
+    { length: 100000 },
+    (_, i) => ({
+      name: `Item ${i + 1}`
+    })
+  );
+
+  useEffect(() => {
+
+    const virtualScroll =
+      new UniversalVirtualScroll({
+
+        viewport:
+          viewportRef.current,
+
+        content:
+          contentRef.current,
+
+        items,
+
+        itemHeight: 100,
+
+        itemWidth: 200,
+
+        onUpdate: (
+          items,
+          top,
+          bottom
+        ) => {
+
+          setVisibleItems(items);
+
+          setPaddingTop(top);
+
+          setPaddingBottom(bottom);
+        }
+      });
+
+    return () => {
+
+      virtualScroll.destroy();
+
+    };
+
+  }, []);
+
+  return (
+
+    <div
+      ref={viewportRef}
+      className="viewport">
+
+      <div
+        ref={contentRef}
+        style={{
+          paddingTop,
+          paddingBottom
+        }}>
+
+        {
+
+          visibleItems.map(item => (
+
+            <div
+              key={item.name}
+              className="card">
+
+              {item.name}
+
+            </div>
+
+          ))
+        }
+
+      </div>
+
+    </div>
+  );
+}
+
+export default App;
+```
+
+---
+
+## App.css
+
+```css
+.viewport {
+  height: 100vh;
+  overflow-y: auto;
+}
+
+.card {
+  height: 100px;
+}
+```
+
+---
+
+# Next.js Example
+
+## app/page.jsx
+
+```jsx
+'use client';
+
+import {
+  useEffect,
+  useRef,
+  useState
+} from 'react';
+
+import {
+  UniversalVirtualScroll
+} from 'universal-virtual-scroll';
+
+export default function Home() {
+
+  const viewportRef = useRef(null);
+
+  const contentRef = useRef(null);
+
+  const [visibleItems, setVisibleItems] =
+    useState([]);
+
+  const [paddingTop, setPaddingTop] =
+    useState(0);
+
+  const [paddingBottom, setPaddingBottom] =
+    useState(0);
+
+  const items = Array.from(
+    { length: 100000 },
+    (_, i) => ({
+      name: `Item ${i + 1}`
+    })
+  );
+
+  useEffect(() => {
+
+    const virtualScroll =
+      new UniversalVirtualScroll({
+
+        viewport:
+          viewportRef.current,
+
+        content:
+          contentRef.current,
+
+        items,
+
+        itemHeight: 100,
+
+        itemWidth: 200,
+
+        onUpdate: (
+          items,
+          top,
+          bottom
+        ) => {
+
+          setVisibleItems(items);
+
+          setPaddingTop(top);
+
+          setPaddingBottom(bottom);
+        }
+      });
+
+    return () => {
+
+      virtualScroll.destroy();
+
+    };
+
+  }, []);
+
+  return (
+
+    <div
+      ref={viewportRef}
+      className="viewport">
+
+      <div
+        ref={contentRef}
+        style={{
+          paddingTop,
+          paddingBottom
+        }}>
+
+        {
+
+          visibleItems.map(item => (
+
+            <div
+              key={item.name}
+              className="card">
+
+              {item.name}
+
+            </div>
+
+          ))
+        }
+
+      </div>
+
+    </div>
+  );
+}
+```
+
+---
+
+## app/globals.css
+
+```css
+.viewport {
+  height: 100vh;
+  overflow-y: auto;
+}
+
+.card {
+  height: 100px;
+}
+```
+
+---
+
+# Configuration
+
+| Option | Type | Description |
+|---|---|---|
+| viewport | HTMLElement | Scroll container |
+| content | HTMLElement | Content wrapper |
+| items | Array | Full dataset |
+| itemHeight | Number | Item height |
+| itemWidth | Number | Item width |
+| onUpdate | Function | Update callback |
+
+---
+
+# Methods
+
+## updateItems
+
+```js
+virtualScroll.updateItems(newItems);
+```
+
+---
+
+## destroy
+
+```js
+virtualScroll.destroy();
+```
+
+---
+
+# Important
+
+- `viewport` must have fixed height
+- `viewport` must use `overflow-y: auto`
+- `itemHeight` must match actual item height
+- `itemWidth` must match actual item width
+
+---
+
+# License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,128 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  UniversalVirtualScroll: () => UniversalVirtualScroll
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/virtual-scroll-generic.ts
+var UniversalVirtualScroll = class {
+  constructor(config) {
+    this.viewport = config.viewport;
+    this.content = config.content;
+    this.items = config.items || [];
+    this.itemHeight = config.itemHeight || null;
+    this.itemWidth = config.itemWidth || null;
+    this.buffer = config.buffer || 5;
+    this.onUpdate = config.onUpdate;
+    this.scrollListener = () => this.calculate();
+    this.resizeListener = () => this.calculate();
+    this.viewport.addEventListener(
+      "scroll",
+      this.scrollListener,
+      { passive: true }
+    );
+    window.addEventListener(
+      "resize",
+      this.resizeListener
+    );
+    requestAnimationFrame(() => {
+      this.detectItemSize();
+      this.calculate();
+    });
+  }
+  detectItemSize() {
+    const firstItem = this.content.querySelector(
+      "[data-virtual-item]"
+    );
+    if (!firstItem) {
+      return false;
+    }
+    const rect = firstItem.getBoundingClientRect();
+    this.itemHeight || (this.itemHeight = rect.height);
+    this.itemWidth || (this.itemWidth = rect.width);
+    return true;
+  }
+  calculate() {
+    if (!this.items.length) {
+      this.onUpdate([], 0, 0);
+      return;
+    }
+    if (!this.itemHeight || !this.itemWidth) {
+      const detected = this.detectItemSize();
+      if (!detected) return;
+    }
+    const viewportHeight = this.viewport.clientHeight;
+    const viewportWidth = this.viewport.clientWidth;
+    const cols = Math.max(
+      1,
+      Math.floor(
+        viewportWidth / this.itemWidth
+      )
+    );
+    const visibleRows = Math.ceil(
+      viewportHeight / this.itemHeight
+    );
+    const pageSize = (visibleRows + this.buffer) * cols;
+    const scrollTop = this.viewport.scrollTop;
+    const startRow = Math.floor(
+      scrollTop / this.itemHeight
+    );
+    const start = Math.max(
+      0,
+      startRow * cols - this.buffer * cols
+    );
+    const end = Math.min(
+      this.items.length,
+      start + pageSize
+    );
+    const slicedList = this.items.slice(start, end);
+    const paddingTop = Math.floor(start / cols) * this.itemHeight;
+    const remainingItems = this.items.length - end;
+    const paddingBottom = Math.ceil(
+      remainingItems / cols
+    ) * this.itemHeight;
+    this.onUpdate(
+      slicedList,
+      paddingTop,
+      paddingBottom
+    );
+  }
+  updateItems(items) {
+    this.items = items;
+    this.calculate();
+  }
+  destroy() {
+    this.viewport.removeEventListener(
+      "scroll",
+      this.scrollListener
+    );
+    window.removeEventListener(
+      "resize",
+      this.resizeListener
+    );
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  UniversalVirtualScroll
+});

package/dist/index.d.cts

@@ -0,0 +1,27 @@
+interface UniversalVirtualScrollConfig {
+    viewport: HTMLElement;
+    content: HTMLElement;
+    items: any[];
+    itemHeight?: number;
+    itemWidth?: number;
+    buffer?: number;
+    onUpdate: (visibleItems: any[], paddingTop: number, paddingBottom: number) => void;
+}
+declare class UniversalVirtualScroll {
+    private viewport;
+    private content;
+    private items;
+    private itemHeight;
+    private itemWidth;
+    private buffer;
+    private onUpdate;
+    private scrollListener;
+    private resizeListener;
+    constructor(config: UniversalVirtualScrollConfig);
+    private detectItemSize;
+    calculate(): void;
+    updateItems(items: any[]): void;
+    destroy(): void;
+}
+
+export { UniversalVirtualScroll };

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+interface UniversalVirtualScrollConfig {
+    viewport: HTMLElement;
+    content: HTMLElement;
+    items: any[];
+    itemHeight?: number;
+    itemWidth?: number;
+    buffer?: number;
+    onUpdate: (visibleItems: any[], paddingTop: number, paddingBottom: number) => void;
+}
+declare class UniversalVirtualScroll {
+    private viewport;
+    private content;
+    private items;
+    private itemHeight;
+    private itemWidth;
+    private buffer;
+    private onUpdate;
+    private scrollListener;
+    private resizeListener;
+    constructor(config: UniversalVirtualScrollConfig);
+    private detectItemSize;
+    calculate(): void;
+    updateItems(items: any[]): void;
+    destroy(): void;
+}
+
+export { UniversalVirtualScroll };

package/dist/index.js

@@ -0,0 +1,101 @@
+// src/virtual-scroll-generic.ts
+var UniversalVirtualScroll = class {
+  constructor(config) {
+    this.viewport = config.viewport;
+    this.content = config.content;
+    this.items = config.items || [];
+    this.itemHeight = config.itemHeight || null;
+    this.itemWidth = config.itemWidth || null;
+    this.buffer = config.buffer || 5;
+    this.onUpdate = config.onUpdate;
+    this.scrollListener = () => this.calculate();
+    this.resizeListener = () => this.calculate();
+    this.viewport.addEventListener(
+      "scroll",
+      this.scrollListener,
+      { passive: true }
+    );
+    window.addEventListener(
+      "resize",
+      this.resizeListener
+    );
+    requestAnimationFrame(() => {
+      this.detectItemSize();
+      this.calculate();
+    });
+  }
+  detectItemSize() {
+    const firstItem = this.content.querySelector(
+      "[data-virtual-item]"
+    );
+    if (!firstItem) {
+      return false;
+    }
+    const rect = firstItem.getBoundingClientRect();
+    this.itemHeight || (this.itemHeight = rect.height);
+    this.itemWidth || (this.itemWidth = rect.width);
+    return true;
+  }
+  calculate() {
+    if (!this.items.length) {
+      this.onUpdate([], 0, 0);
+      return;
+    }
+    if (!this.itemHeight || !this.itemWidth) {
+      const detected = this.detectItemSize();
+      if (!detected) return;
+    }
+    const viewportHeight = this.viewport.clientHeight;
+    const viewportWidth = this.viewport.clientWidth;
+    const cols = Math.max(
+      1,
+      Math.floor(
+        viewportWidth / this.itemWidth
+      )
+    );
+    const visibleRows = Math.ceil(
+      viewportHeight / this.itemHeight
+    );
+    const pageSize = (visibleRows + this.buffer) * cols;
+    const scrollTop = this.viewport.scrollTop;
+    const startRow = Math.floor(
+      scrollTop / this.itemHeight
+    );
+    const start = Math.max(
+      0,
+      startRow * cols - this.buffer * cols
+    );
+    const end = Math.min(
+      this.items.length,
+      start + pageSize
+    );
+    const slicedList = this.items.slice(start, end);
+    const paddingTop = Math.floor(start / cols) * this.itemHeight;
+    const remainingItems = this.items.length - end;
+    const paddingBottom = Math.ceil(
+      remainingItems / cols
+    ) * this.itemHeight;
+    this.onUpdate(
+      slicedList,
+      paddingTop,
+      paddingBottom
+    );
+  }
+  updateItems(items) {
+    this.items = items;
+    this.calculate();
+  }
+  destroy() {
+    this.viewport.removeEventListener(
+      "scroll",
+      this.scrollListener
+    );
+    window.removeEventListener(
+      "resize",
+      this.resizeListener
+    );
+  }
+};
+export {
+  UniversalVirtualScroll
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "universal-virtual-scroll",
+  "version": "1.0.0",
+  "description": "A lightweight and framework-agnostic virtual scrolling library.",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --watch"
+  },
+  "keywords": [
+    "virtual-scroll",
+    "virtualization",
+    "infinite-scroll",
+    "performance",
+    "angular",
+    "react",
+    "nextjs",
+    "typescript",
+    "scrolling"
+  ],
+  "author": "Tejas Patil",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tejaspatil-web/universal-virtual-scroll.git"
+  },
+  "homepage": "https://github.com/tejaspatil-web/universal-virtual-scroll#readme",
+  "bugs": {
+    "url": "https://github.com/tejaspatil-web/universal-virtual-scroll/issues"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}