@dipakshiroya/react-progressive-image

A lightweight, flexible React component for progressive image loading — featuring blurred placeholders, lazy loading, aspect ratio support, and fallbacks.
No more manual hacks for skeletons or blurred thumbnails.

✨ Features

• 🖼️ Progressive loading (blurred low-res placeholder)
• 💤 Lazy loading via native loading="lazy"
• 🧩 Maintains aspect ratio to prevent layout shifts
• 🚨 Fallback image if load fails
• 🎨 Smooth fade-in transition
• ⚙️ Fully typed with TypeScript
• 🪶 Zero dependencies

📦 Installation

npm install @dipakshiroya/react-progressive-image
# or
yarn add @dipakshiroya/react-progressive-image
# or
pnpm add @dipakshiroya/react-progressive-image

Note: use --force if you face any issues

🚀 Usage

Basic Example

import React from "react";
import ProgressiveImage from "@dipakshiroya/react-progressive-image";

export default function App() {
  return (
    <div style={{ maxWidth: 600, margin: "0 auto" }}>
      <h1>Progressive Image Example</h1>

      <ProgressiveImage
        src="https://picsum.photos/id/1015/800/500"           // Full-res image
        placeholderSrc="https://picsum.photos/id/1015/80/50"  // Blurred low-res preview
        fallbackSrc="https://via.placeholder.com/800x500"     // Fallback if src fails
        aspectRatio={800 / 500}                               // Maintain aspect ratio
        alt="Mountain landscape"
        className="rounded-lg shadow-lg"
      />
    </div>
  );
}

📐 Props

| Prop | Type | Description | Default | |------|------|-------------|----------| | src | string | High-resolution image URL | required | | placeholderSrc | string | Low-resolution / blurred preview | undefined | | fallbackSrc | string | Backup image if main fails | undefined | | aspectRatio | number | Keeps layout consistent before load | undefined | | className | string | Extra CSS class names | "" | | style | React.CSSProperties | Inline styles for wrapper | {} | | ...imgProps | React.ImgHTMLAttributes<HTMLImageElement> | Any native <img> props | — |

⚡ Advanced Example

Image Grid with Automatic Blurred Previews

const images = [1011, 1012, 1013];

export const Gallery = () => (
  <div style={{ display: "grid", gridTemplateColumns: "repeat(3, 1fr)", gap: 16 }}>
    {images.map(id => (
      <ProgressiveImage
        key={id}
        src={`https://picsum.photos/id/${id}/400/300`}
        placeholderSrc={`https://picsum.photos/id/${id}/40/30`}
        aspectRatio={4 / 3}
        alt={`Image ${id}`}
      />
    ))}
  </div>
);

💡 Tips

• Generate low-res placeholders using Picsum, ImageKit, or Cloudinary.
• Fully compatible with Tailwind, MUI, Chakra, etc.
• Works with SSR (Next.js) and CSR (Vite, CRA) environments.

🧱 TypeScript Support

Type definitions are built-in.
You can import props directly:

import ProgressiveImage, { ProgressiveImageProps } from "@dipakshiroya/react-progressive-image";

🧩 Compatible With

• React 18+
• Vite
• Next.js
• CRA
• Remix

🛠️ Development

If contributing or testing locally:

git clone https://github.com/dipakshiroya/react-progressive-image
cd react-progressive-image
npm install
npm run build
npm link

Then in another project:

npm link @dipakshiroya/react-progressive-image

🪪 License

MIT © Dipak Shiroya

🌟 Support

If you like this package, please ⭐ it on GitHub!
Feedback and contributions are always welcome.