I Imgx Docs
Selective image enhancement

Only upgrade the images you mean to.

Imgx is a lightweight, framework-agnostic library for image loading on the web. It targets only opted-in images, adds lazy loading, transitions, retry logic, fallbacks, and pluggable renderers, and leaves everything else alone.

Get started Learn more
Zero runtime dependencies ES module + CDN build Built-in renderer system

Current feature set

Focused features that reflect the current codebase and project goals, without inflated claims.

Selective targeting

Imgx processes only images marked with the configured `data-*` attribute and ignores every other image in the document.

Layered configuration

Use global defaults, per-image `data-*` overrides, and programmatic per-instance overrides without losing fallback behavior.

Lazy loading with fallback

Uses `IntersectionObserver` when available and still loads correctly in environments where it is not supported.

Built-in renderers

Ships with skeleton, SVG animation, blur preview, dominant color, and fallback renderers in a pluggable system.

Transitions and retries

Supports fade, blur, and scale transitions, plus retry attempts, delays, and fallback source rotation.

Adaptive behavior

Includes network-aware auto mode and cache-aware decisions to favor lighter behavior where it makes sense.

Project objectives

Imgx is meant to stay small, predictable, and easy to extend.

What it optimizes for

  • Minimal setup for default usage.
  • Fine-grained control when individual images need different behavior.
  • Clear separation between core loading logic and renderer behavior.
  • Framework-agnostic usage across plain HTML, apps, and generated sites.
  • Open-source friendliness with readable source and simple extension points.

What it avoids

  • Touching images you did not opt into.
  • Heavy runtime dependencies.
  • Bulky UI abstractions tied to one framework.
  • Single-purpose placeholder logic hardcoded into the core.
  • Marketing claims that do not match the shipped library.

Simple usage

Use the source modules during development or the generated CDN build for direct browser usage.

ES module

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

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

CDN build

<script src="./dist/imgx.min.js"></script>
<script>
  const gallery = Imgx.createImgx({
    placeholder: {
      renderer: "skeleton"
    }
  });

  gallery.init();
</script>

Usage examples

Common real-world patterns that match the current library behavior.

Priority image

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

Blur preview

<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"
/>

Retry and fallback

<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"
/>

Custom target attribute

import { createImgx } from "@amaanwarsi/imgx";

const productImages = createImgx({
  targetAttribute: "data-product-img"
});

productImages.init();

Documentation

The project docs are split by usage, API, and renderer behavior so the core path stays easy to scan.

Reference site

Browse the complete web docs for setup, API surface, overrides, renderers, and examples.

Getting started

Quick path for first use, rescanning, custom target attributes, and common per-image patterns.

API notes

Read the current exports, instance methods, lifecycle states, and top-level config areas.