Progressive Image Component

A React progressive image component with:

• Blurry thumbnail placeholder
• Lazy loading via IntersectionObserver
• Responsive AVIF srcSet
• Smooth fade-in when high-resolution image is loaded

Install

npm install @aleafrodo/progressive-image-component

Usage

import ProgressiveImage from "@your-scope/progressive-image-component";

export default function Hero() {
  return (
    <ProgressiveImage
      baseName="sample-photo"
      alt="A mountain at sunrise"
      width="100%"
      aspectRatio="16/9"
      borderRadius="1rem"
      imagePath="/images/"
    />
  );
}

The component expects image files following this naming convention:

• {baseName}-thumbnail.jpg
• {baseName}-seo.jpg
• {baseName}-{width}w.avif (for each width in your set)

Example for baseName="sample-photo":

• sample-photo-thumbnail.jpg
• sample-photo-seo.jpg
• sample-photo-100w.avif, sample-photo-200w.avif, etc.

Props

• baseName: string (required)
• alt: string (required)
• showBlurry?: boolean (default: true)
• flexGrow?: string | number (default: "1")
• aspectRatio?: string (default: "16/9")
• shadow?: boolean (default: true)
• borderRadius?: string (default: "0")
• round?: boolean (default: false)
• width?: string | number (default: "auto")
• height?: string | number (default: "auto")
• imagePath?: string (default: "/images/")
• widths?: number[] (default built-in AVIF width list)

Local Development

npm install
npm run build

Image Generation Script

A helper script is included at scripts/compression.sh to generate AVIF variants and JPG placeholders from originals.

Dependencies:

• imagemagick
• libavif
• jpegoptim