StringLazy Module

Stream remote images only when they enter view. StringLazy probes intrinsic dimensions up front, locks in aspect ratio, and swaps in the real image once layout is safe.

HTML Attributes

Module Snapshot

• Target selector: img[string-lazy] or img[data-string-lazy]
• Lifecycle hooks: waits for object:inview before decoding the actual bytes
• Inline helpers: adds lazyLoad, -aspect-ready, then -loaded classes as it progresses
• Aspect ratio: writes style="aspect-ratio: w / h" once dimensions are known to prevent layout jumps
• Event channel: global image:load:all when every pending lazy image has completed
• Network behavior: streams the remote file, inspects the first bytes for PNG/JPEG/WebP headers, and falls back to img.src if CORS blocks the fetch

Basic Usage

import StringTune, { StringLazy } from '@fiddle-digital/string-tune';

const stringTune = StringTune.getInstance();
stringTune.use(StringLazy);
stringTune.start(60);

<img string-lazy="/images/hero/full-res.webp" alt="Studio workspace" width="960" height="640" class="hero-image" />

.hero-image.lazyLoad {
  background: var(--skeleton-color, #0f0f0f);
  filter: blur(8px);
  transition: filter 220ms ease;
}

.hero-image.-loaded {
  filter: none;
}

.hero-image.-aspect-ready {
  object-fit: cover;
}

How It Works

• In-view trigger: when the surrounding StringTune ecosystem marks the <img> as inView, the module starts resolving both aspect data and image bytes.
• Dimension probe: a streaming fetch reads the first kilobytes, parses PNG/JPEG/WebP headers, and sets aspect-ratio inline the moment width and height are known.
• Deferred activation: the real network response is stored as a blob URL. The module waits for both aspect data and viewport presence before swapping the src.
• Graceful fallback: if streaming fails (for example, due to CORS), it reverts to assigning the original URL but keeps the lazy workflow intact.
• Cleanup: aborts pending fetches and revokes blob URLs when elements disconnect to avoid leaks.
• Class states: lazyLoad marks initialisation, -aspect-ready indicates ratio lock-in, and -loaded flips on after the real image fires load.

Event Signal

stringTune.on('image:load:all', () => {
  document.body.classList.add('images-ready');
});

StringLazy keeps image-heavy layouts stable and responsive—flag your sources with string-lazy, craft loading states with the provided classes, and let the module coordinate the rest.