use-images-tracker 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HBI Developer
+
+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,75 @@
+# use-images-tracker
+
+React Hook to check whether images inside a tracked element/component are loaded.
+
+Features
+
+- Lightweight React hook that tracks images inside a container and reports load/failure state.
+
+Install
+
+```bash
+npm install use-images-tracker
+```
+
+Peer dependencies
+
+- This package requires React (>=16.8.0).
+
+Usage
+
+```tsx
+import React from "react";
+import useImagesTracker from "use-images-tracker";
+
+function Example() {
+  const { tracker, isLoaded, failures, repeating } = useImagesTracker();
+
+  return (
+    <div>
+      <div ref={tracker}>
+        <img src="/path/to/image1.jpg" alt="img1" />
+        <img src="/path/to/image2.jpg" alt="img2" />
+      </div>
+
+      {isLoaded ? <p>All images loaded</p> : <p>Loading images…</p>}
+
+      {failures.length > 0 && (
+        <ul>
+          {failures.map((f, i) => (
+            <li key={i}>
+              {f.url} — code: {f.code}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+export default Example;
+```
+
+API
+
+- `tracker`: React ref to attach to the container element that holds images.
+- `isLoaded`: boolean, becomes `true` when all tracked images are finished (loaded or errored).
+- `failures`: array of failure records `{ code, image, url }` for images that errored.
+- `repeating`: function to restart tracking (useful when images change dynamically).
+
+Build from source
+
+```bash
+npm install
+npm run build
+```
+
+Publish
+
+```bash
+npm publish --access public
+```
+
+License
+
+This project is licensed under the MIT License

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export default function useImagesTracker(): {
+    tracker: import("react").RefObject<any>;
+    isLoaded: boolean;
+    failures: {
+        code: number;
+        image: HTMLImageElement;
+        url: string;
+    }[];
+    repeating: () => void;
+};

package/dist/index.js

@@ -0,0 +1,119 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+import { useEffect, useRef, useState } from "react";
+export default function useImagesTracker() {
+    var _this = this;
+    var tracker = useRef(null), _a = useState(false), isStarted = _a[0], setIsStarted = _a[1], isFirstTime = useRef(true), images = useRef([]), _b = useState([]), failures = _b[0], setFailures = _b[1], _c = useState(0), counter = _c[0], setCounter = _c[1], _d = useState(false), isLoaded = _d[0], setIsLoaded = _d[1], tracking = function () {
+        var _a;
+        if (isStarted)
+            return;
+        setIsStarted(true);
+        images.current = ((_a = tracker.current) === null || _a === void 0 ? void 0 : _a.querySelectorAll("img")) || [];
+        if (images.current.length === 0) {
+            setIsLoaded(true);
+            return;
+        }
+        var increaseCounter = function () {
+            setCounter(function (prev) { return prev + 1; });
+        };
+        [].forEach.call(images.current, function (image) {
+            if (image.complete)
+                increaseCounter();
+            else {
+                image.addEventListener("load", increaseCounter);
+                image.addEventListener("error", function () { return __awaiter(_this, void 0, void 0, function () {
+                    var error, url, _1;
+                    return __generator(this, function (_a) {
+                        switch (_a.label) {
+                            case 0:
+                                error = { image: image, code: 0, url: image.src };
+                                increaseCounter();
+                                _a.label = 1;
+                            case 1:
+                                _a.trys.push([1, 3, , 4]);
+                                return [4 /*yield*/, fetch(image.src)];
+                            case 2:
+                                url = _a.sent();
+                                if (!url.ok) {
+                                    error.code = url.status;
+                                }
+                                return [3 /*break*/, 4];
+                            case 3:
+                                _1 = _a.sent();
+                                error.code = 500;
+                                return [3 /*break*/, 4];
+                            case 4:
+                                setFailures(function (prev) { return __spreadArray(__spreadArray([], prev, true), [error], false); });
+                                return [2 /*return*/];
+                        }
+                    });
+                }); });
+            }
+        });
+    }, repeating = function () {
+        if (!isStarted || isFirstTime.current)
+            return;
+        setCounter(0);
+        setIsLoaded(false);
+        setTimeout(function () {
+            setIsStarted(false);
+        }, 0);
+    };
+    useEffect(function () {
+        tracking();
+    }, []);
+    useEffect(function () {
+        if (!isStarted)
+            tracking();
+    }, [isStarted]);
+    useEffect(function () {
+        if (counter >= images.current.length) {
+            setIsLoaded(true);
+            isFirstTime.current = false;
+        }
+    }, [counter]);
+    return { tracker: tracker, isLoaded: isLoaded, failures: failures, repeating: repeating };
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "use-images-tracker",
+  "version": "1.0.0",
+  "description": "React Hook to Check if images inside tracked element/component is loaded.",
+  "homepage": "https://github.com/HBI-Developer/use-images-tracker",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "keywords": [
+    "react",
+    "hook",
+    "track",
+    "images",
+    "loaded",
+    "track images",
+    "images loaded",
+    "is loaded",
+    "is images loaded"
+  ],
+  "author": "HBI Developer",
+  "license": "MIT",
+  "type": "module",
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "typescript": "^5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HBI-Developer/use-images-tracker.git"
+  },
+  "bugs": {
+    "url": "https://github.com/HBI-Developer/use-images-tracker/issues"
+  }
+}