lazyvid 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artem Tyshchuk
+
+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,147 @@
+# lazyvid
+
+Lazy-load `<video>` sources with predictable behavior.
+
+`lazyvid` renders an empty `<video>` element and injects `<source>` tags only when the element enters the viewport.  
+Until then — nothing downloads.
+
+It relies on IntersectionObserver for visibility tracking and lets the browser handle native format selection (`webm`, `mp4`, etc).
+
+~2 KB. Zero dependencies. Full TypeScript support.
+
+```tsx
+<LazyVideo
+  sources={[
+    { src: "/hero.webm", type: "video/webm" },
+    { src: "/hero.mp4", type: "video/mp4" },
+  ]}
+  muted
+  autoPlay
+  loop
+/>
+```
+
+Single component. No additional setup.
+
+## Why?
+
+Browsers start fetching `<video>` sources as soon as `<source>` elements are present in the DOM.
+On media-heavy pages, this means unnecessary bandwidth usage and background CPU activity — even if the user never scrolls to the video.
+
+`lazyvid` avoids that by delaying source injection until the element becomes visible (with configurable preload offset).
+
+- No user-agent checks.
+- No format guessing.
+
+The browser still decides which source to play.
+
+## What it does
+
+- Renders an empty `<video>`
+- Observes it with IntersectionObserver
+- Injects `<source>` elements when it enters the viewport
+- Optionally pauses playback when it leaves
+
+That’s it.
+
+## Install
+
+```bash
+npm install lazyvid
+```
+
+Requires React 18 or 19.
+
+## Usage
+
+### Basic — just lazy load it
+
+```tsx
+import { LazyVideo } from "lazyvid";
+
+<LazyVideo
+  sources={[
+    { src: "/promo.webm", type: "video/webm" },
+    { src: "/promo.mp4", type: "video/mp4" },
+  ]}
+  controls
+/>;
+```
+
+Sources are listed in priority order. The browser takes the first format it supports — put your lightest format first.
+
+### Background video that pauses off-screen
+
+```tsx
+<LazyVideo
+  sources={[
+    { src: "/bg.webm", type: "video/webm" },
+    { src: "/bg.mp4", type: "video/mp4" },
+  ]}
+  autoPlay
+  muted
+  loop
+  pauseOnLeave
+  style={{ width: "100%", objectFit: "cover" }}
+/>
+```
+
+When the user scrolls away — video pauses. Scrolls back — resumes. No wasted CPU on invisible playback.
+
+### With poster and loading callback
+
+```tsx
+const [ready, setReady] = useState(false);
+
+<div style={{ position: "relative" }}>
+  {!ready && <div className="skeleton" />}
+  <LazyVideo
+    sources={[{ src: "/intro.mp4", type: "video/mp4" }]}
+    poster="/intro-thumb.jpg"
+    controls
+    onLoaded={() => setReady(true)}
+  />
+</div>;
+```
+
+### Start loading earlier
+
+By default, loading starts 200px before the video is visible. Want more buffer?
+
+```tsx
+<LazyVideo
+  sources={[{ src: "/hero.mp4", type: "video/mp4" }]}
+  rootMargin="500px"
+  muted
+  autoPlay
+/>
+```
+
+## Props
+
+| Prop           | Type                  | Default   | Description                                     |
+| -------------- | --------------------- | --------- | ----------------------------------------------- |
+| `sources`      | `VideoSource[]`       | required  | `{ src, type }` objects in priority order       |
+| `threshold`    | `number`              | `0`       | How much of the element should be visible (0–1) |
+| `rootMargin`   | `string`              | `"200px"` | Start loading before the element is in view     |
+| `pauseOnLeave` | `boolean`             | `false`   | Pause when out of viewport, resume when back    |
+| `onLoaded`     | `() => void`          | —         | Fires when sources are injected                 |
+| `...rest`      | `VideoHTMLAttributes` | —         | Any native `<video>` attribute works            |
+
+## How it works
+
+1. Renders an empty `<video>` — nothing downloads
+2. IntersectionObserver watches it (with `rootMargin` for early preloading)
+3. Element enters viewport → `<source>` tags injected → browser picks best format → loading starts
+4. Observer disconnects (one-time job)
+5. If `pauseOnLeave` is on, a second observer manages play/pause on scroll
+
+## Types
+
+```ts
+import { LazyVideo, type VideoSource } from "lazyvid";
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,17 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type VideoSource = {
+    type: string;
+    src: string;
+};
+
+type LazyVideoProps = {
+    sources: VideoSource[];
+    threshold?: number;
+    rootMargin?: string;
+    pauseOnLeave?: boolean;
+    onLoaded?: () => void;
+} & React.VideoHTMLAttributes<HTMLVideoElement>;
+declare const LazyVideo: ({ sources, threshold, rootMargin, pauseOnLeave, onLoaded, ...videoProps }: LazyVideoProps) => react_jsx_runtime.JSX.Element;
+
+export { LazyVideo, type VideoSource };

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type VideoSource = {
+    type: string;
+    src: string;
+};
+
+type LazyVideoProps = {
+    sources: VideoSource[];
+    threshold?: number;
+    rootMargin?: string;
+    pauseOnLeave?: boolean;
+    onLoaded?: () => void;
+} & React.VideoHTMLAttributes<HTMLVideoElement>;
+declare const LazyVideo: ({ sources, threshold, rootMargin, pauseOnLeave, onLoaded, ...videoProps }: LazyVideoProps) => react_jsx_runtime.JSX.Element;
+
+export { LazyVideo, type VideoSource };

package/dist/index.js

@@ -0,0 +1,111 @@
+"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, {
+  LazyVideo: () => LazyVideo
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/react/LazyVideo.tsx
+var import_react = require("react");
+
+// src/core/createLazyObserver.ts
+var createLazyObserver = ({
+  element,
+  onIntersect,
+  options
+}) => {
+  if (typeof window === "undefined") return;
+  const observer = new IntersectionObserver((entries) => {
+    if (entries[0].isIntersecting) {
+      onIntersect();
+      observer.unobserve(element);
+    }
+  }, options);
+  observer.observe(element);
+  return () => observer.disconnect();
+};
+
+// src/core/createPlaybackObserver.ts
+var createPlaybackObserver = ({
+  video,
+  options
+}) => {
+  if (typeof window === "undefined") return;
+  const observer = new IntersectionObserver((entries) => {
+    if (entries[0].isIntersecting) {
+      video.play().catch(() => {
+      });
+    } else {
+      video.pause();
+    }
+  }, options);
+  observer.observe(video);
+  return () => observer.disconnect();
+};
+
+// src/react/LazyVideo.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var LazyVideo = ({
+  sources,
+  threshold = 0,
+  rootMargin = "200px",
+  pauseOnLeave = false,
+  onLoaded,
+  ...videoProps
+}) => {
+  const videoRef = (0, import_react.useRef)(null);
+  const sourcesRef = (0, import_react.useRef)(sources);
+  const onLoadedRef = (0, import_react.useRef)(onLoaded);
+  const [loaded, setLoaded] = (0, import_react.useState)(false);
+  sourcesRef.current = sources;
+  onLoadedRef.current = onLoaded;
+  (0, import_react.useEffect)(() => {
+    const elem = videoRef.current;
+    if (!elem) return;
+    return createLazyObserver({
+      element: elem,
+      options: { threshold, rootMargin },
+      onIntersect: () => {
+        if (sourcesRef.current.length === 0) return;
+        sourcesRef.current.forEach(({ src, type }) => {
+          const source = document.createElement("source");
+          source.src = src;
+          source.type = type;
+          elem.appendChild(source);
+        });
+        elem.load();
+        setLoaded(true);
+        onLoadedRef.current?.();
+      }
+    });
+  }, [threshold, rootMargin]);
+  (0, import_react.useEffect)(() => {
+    const video = videoRef.current;
+    if (!video || !loaded || !pauseOnLeave) return;
+    return createPlaybackObserver({ video });
+  }, [loaded, pauseOnLeave]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("video", { ref: videoRef, ...videoProps });
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LazyVideo
+});

package/dist/index.mjs

@@ -0,0 +1,84 @@
+// src/react/LazyVideo.tsx
+import { useEffect, useRef, useState } from "react";
+
+// src/core/createLazyObserver.ts
+var createLazyObserver = ({
+  element,
+  onIntersect,
+  options
+}) => {
+  if (typeof window === "undefined") return;
+  const observer = new IntersectionObserver((entries) => {
+    if (entries[0].isIntersecting) {
+      onIntersect();
+      observer.unobserve(element);
+    }
+  }, options);
+  observer.observe(element);
+  return () => observer.disconnect();
+};
+
+// src/core/createPlaybackObserver.ts
+var createPlaybackObserver = ({
+  video,
+  options
+}) => {
+  if (typeof window === "undefined") return;
+  const observer = new IntersectionObserver((entries) => {
+    if (entries[0].isIntersecting) {
+      video.play().catch(() => {
+      });
+    } else {
+      video.pause();
+    }
+  }, options);
+  observer.observe(video);
+  return () => observer.disconnect();
+};
+
+// src/react/LazyVideo.tsx
+import { jsx } from "react/jsx-runtime";
+var LazyVideo = ({
+  sources,
+  threshold = 0,
+  rootMargin = "200px",
+  pauseOnLeave = false,
+  onLoaded,
+  ...videoProps
+}) => {
+  const videoRef = useRef(null);
+  const sourcesRef = useRef(sources);
+  const onLoadedRef = useRef(onLoaded);
+  const [loaded, setLoaded] = useState(false);
+  sourcesRef.current = sources;
+  onLoadedRef.current = onLoaded;
+  useEffect(() => {
+    const elem = videoRef.current;
+    if (!elem) return;
+    return createLazyObserver({
+      element: elem,
+      options: { threshold, rootMargin },
+      onIntersect: () => {
+        if (sourcesRef.current.length === 0) return;
+        sourcesRef.current.forEach(({ src, type }) => {
+          const source = document.createElement("source");
+          source.src = src;
+          source.type = type;
+          elem.appendChild(source);
+        });
+        elem.load();
+        setLoaded(true);
+        onLoadedRef.current?.();
+      }
+    });
+  }, [threshold, rootMargin]);
+  useEffect(() => {
+    const video = videoRef.current;
+    if (!video || !loaded || !pauseOnLeave) return;
+    return createPlaybackObserver({ video });
+  }, [loaded, pauseOnLeave]);
+  return /* @__PURE__ */ jsx("video", { ref: videoRef, ...videoProps });
+};
+export {
+  LazyVideo
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "lazyvid",
+  "version": "0.1.0",
+  "description": "Lightweight lazy-loading video component with IntersectionObserver",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "keywords": [
+    "video",
+    "lazy-loading",
+    "intersection-observer",
+    "react"
+  ],
+  "author": "",
+  "license": "MIT",
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.0.0",
+    "jsdom": "^28.1.0",
+    "prettier": "^3.8.1",
+    "react": "^19.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}