Docs

Setup

Installation

npm install @amaanwarsi/imgx

By default, Imgx processes only images marked with data-imgx. That keeps behavior explicit and ensures untargeted images stay untouched.

<img
  data-imgx
  data-imgx-src="/images/photo-large.jpg"
  alt="Example photo"
  width="1200"
  height="800"
/>

<script type="module">
  import imgx from "./src/index.js";
</script>

Usage

import imgx from "./src/index.js";

import { createImgx } from "./src/index.js";

const gallery = createImgx({
  placeholder: {
    renderer: "blurPreview"
  },
  transition: {
    type: "blur",
    duration: 520
  }
});

gallery.init();

Rescan dynamic content

gallery.rescan(document.querySelector("[data-gallery]"));

Custom target attribute

If you change targetAttribute, the related override attributes follow the same prefix.

const custom = createImgx({
  targetAttribute: "data-photox"
});

custom.init();

// HTML
// <img data-photox data-photox-src="/image.jpg" alt="Photo" />

Examples

Priority image that skips lazy loading

<img
  data-imgx
  data-imgx-src="/images/hero.jpg"
  data-imgx-priority="high"
  alt="Hero image"
  width="1600"
  height="900"
/>

Blur preview with blur transition

<img
  data-imgx
  data-imgx-src="/images/card.jpg"
  data-imgx-preview="/images/card-preview.jpg"
  data-imgx-renderer="blurPreview"
  data-imgx-transition="blur"
  alt="Card image"
/>

Retry logic with fallback sources

<img
  data-imgx
  data-imgx-src="/images/primary.jpg"
  data-imgx-fallback="/images/fallback-a.jpg,/images/fallback-b.jpg"
  data-imgx-retry-attempts="2"
  data-imgx-retry-delay="800"
  alt="Example"
/>

Register a custom renderer

const imgx = createImgx();

imgx.registerRenderer("dots", {
  mount({ overlay }) {
    overlay.innerHTML = `
      <div style="display:grid;place-items:center;width:100%;height:100%;background:#111;color:#fff">
        Loading...
      </div>
    `;

    return {
      update() {},
      destroy() {
        overlay.textContent = "";
      }
    };
  }
});

imgx.init();

Configuration

Imgx supports three layers of configuration:

• global defaults in the instance config
• per-image overrides via attributes like data-imgx-renderer
• programmatic overrides passed during init or rescan

Common per-image overrides

• data-imgx-renderer
• data-imgx-error-renderer
• data-imgx-transition
• data-imgx-lazy
• data-imgx-priority
• data-imgx-preview
• data-imgx-fallback
• data-imgx-retry-attempts
• data-imgx-retry-delay
• data-imgx-skeleton
• data-imgx-radius
• data-imgx-color
• data-imgx-auto

Lifecycle

Each prepared image moves through a predictable internal lifecycle:

• idle
• loading
• loaded
• error

This state flow is what drives placeholder visibility, transition timing, retries, and fallback rendering.

Renderers

Renderers define the visual behavior before load and on failure. Imgx currently ships with five built-in renderers:

• skeleton with static, pulse, and shimmer modes
• svgAnimation
• blurPreview
• dominantColor
• fallback

Register a custom renderer

const dotsRenderer = {
  name: "dots",
  mount({ overlay }) {
    overlay.innerHTML = "<div style='width:100%;height:100%'>Loading</div>";

    return {
      update() {},
      destroy() {
        overlay.textContent = "";
      }
    };
  }
};

const imgx = createImgx();
imgx.registerRenderer("dots", dotsRenderer);

API

CDN build

The repository includes a central build step for browser-friendly distribution files while keeping src/ untouched.

npm run build:cdn

This generates dist/imgx.js and dist/imgx.min.js.

<script src="./dist/imgx.min.js"></script>
<script>
  const gallery = Imgx.createImgx();
  gallery.init();
</script>