@cabraham/react-smart-loader

Smart, network-aware React image component in < 2KB gzipped with zero dependencies.

Lazy loading, blur / shimmer placeholders, exponential-backoff retry, zero-CLS cross-fade transitions, and a global memory cache — all behind a single <SmartImage> component that extends the native <img> API.

Install

npm install @cabraham/react-smart-loader

react and react-dom (>= 18) are peer dependencies. React 19's resource loading (ReactDOM.preload) is used automatically when available.

Usage

import { SmartImage } from '@cabraham/react-smart-loader';

<SmartImage
  src="https://cdn.example.com/hd-product.jpg"
  aspectRatio={16 / 9}
  placeholder="blur"
  blurSource="data:image/png;base64,iVBOR..." // base64, micro-URL, or decoded hash
  priority={false}
  fallbackSrc="/images/fallback-placeholder.png"
  alt="Product photo"
/>

Because SmartImageProps extends React.ImgHTMLAttributes<HTMLImageElement>, every native attribute (alt, className, style, aria-*, onClick, …) just works.

Props

| Prop | Type | Default | Notes | | --- | --- | --- | --- | | src | string | — | High-res source. | | aspectRatio | number | — | e.g. 16 / 9. Reserves space → zero CLS. | | placeholder | 'blur' \| 'shimmer' \| 'none' | 'blur' | Shown until decode. | | blurSource | string | — | base64 / micro-URL / decoded hash. | | priority | boolean | false | Eager load + high fetchPriority (+ React 19 preload). | | preloadNext | string[] | — | Warm neighbours after load (carousels). | | fallbackSrc | string | — | Used after retries are exhausted. | | maxRetries | number | 3 | Backoff: 1s, 2s, 4s. | | networkAware | boolean | true | Degrade on Save-Data / 2G-3G. | | onLoaded / onErrorFinal | () => void | — | Lifecycle callbacks. |

Placeholders

The base component accepts any string in blurSource. To decode a compact hash into a placeholder, import the matching separate entry point — this keeps the decoder out of the base bundle unless you use it:

import { blurHashToDataURL } from '@cabraham/react-smart-loader/blurhash';

const blur = blurHashToDataURL('LGF5?M9F00~q_MOffQWB00%MwbRj', 32, 32);
// → pass to <SmartImage blurSource={blur} />

ThumbHash

@cabraham/react-smart-loader/thumbhash exposes the final API surface, but the decode body is not yet implemented (see src/thumbhash.ts). It throws until a decode strategy is chosen — use @cabraham/react-smart-loader/blurhash or a plain base64/micro-URL in the meantime.

Predictive preloading

Beyond the preloadNext prop (warmed on hover), usePredictivePreload watches scroll velocity and warms upcoming images before they enter the viewport:

import { usePredictivePreload } from '@cabraham/react-smart-loader';

const upcoming = items.map((i) => i.imageUrl);
usePredictivePreload(upcoming, { count: 2, velocityThreshold: 0.4 });

Demo

A live demo lives in demo/ and runs against the package source (no build step — edit src/* and it hot-reloads):

cd demo
npm install
npm run dev   # http://localhost:5173

Development

npm install
npm run build      # tsup → dist (ESM + CJS + .d.ts)
npm test           # vitest
npm run size       # size-limit budget check
npm run typecheck  # tsc --noEmit

Bundle size

| Entry | Gzipped | Ships when | | --- | --- | --- | | @cabraham/react-smart-loader | ~1.7 KB | always | | @cabraham/react-smart-loader/blurhash | ~1.0 KB | imported | | @cabraham/react-smart-loader/thumbhash | ~0.4 KB | imported |

ESM + CJS, full TypeScript types, "sideEffects": false for tree-shaking.

License

MIT © Abraham Christopher