react-blurish-image

React Optimized Image

A lightweight, high-performance React image component inspired by Next.js Image, with automatic optimization, blur placeholders, and lazy loading. Zero dependencies except React.

✨ Features

• 🖼️ Automatic Image Optimization - Generates responsive images with srcSet
• 🔄 Blur Placeholders - Smooth loading transitions with automatic blur generation
• ⚡ Lazy Loading - Built-in lazy loading for better performance
• 📱 Responsive - Perfect for any screen size with automatic srcSet generation
• 🎯 Fill Mode - Container-based sizing like CSS object-fit
• 🛡️ TypeScript - Full type safety included out of the box
• 🔧 Configurable - Optional development warnings and custom loaders
• 📦 Tiny Bundle - No external dependencies, tree-shakeable
• 🚀 Performance - Optimized for Core Web Vitals and page speed
• 🔒 Privacy Safe - No environment detection or data collection

🚀 Installation

bun add react-optimized-image

npm install react-optimized-image

yarn add react-optimized-image

pnpm add react-optimized-image

📖 Quick Start

import { Image } from "react-optimized-image";

function App() {
  return (
    <Image
      src="https://example.com/image.jpg"
      alt="A beautiful landscape"
      width={800}
      height={600}
      placeholder="blur"
      quality={90}
    />
  );
}

🎛️ API Reference

Props

Prop	Type	Default	Description
src	string	required	Image source URL
alt	string	required	Alternative text for accessibility
width	number	undefined	Image width in pixels
height	number	undefined	Image height in pixels
fill	boolean	false	Fill the parent container (like object-fit)
placeholder	'blur' | 'empty'	'empty'	Placeholder type while loading
blurDataURL	string	undefined	Custom blur placeholder (auto-generated if not provided)
quality	number	75	Image quality (1-100)
priority	boolean	false	Load image with high priority (disables lazy loading)
loading	'eager' | 'lazy'	'lazy'	Loading behavior
unoptimized	boolean	false	Skip automatic optimization
loader	ImageLoader	defaultLoader	Custom image loader function
sizes	string	undefined	Responsive image sizes attribute
onLoad	function	undefined	Callback when image loads
onError	function	undefined	Callback when image fails to load
onLoadingComplete	function	undefined	Callback when loading completes

Additional Props

All standard HTML <img> attributes are supported: className, style, crossOrigin, referrerPolicy, decoding, fetchPriority, etc.

📚 Examples

Basic Usage with Blur Placeholder

import { Image } from "react-optimized-image";

<Image
  src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4"
  alt="Mountain landscape"
  width={800}
  height={600}
  placeholder="blur"
  quality={90}
  className="rounded-lg shadow-md"
/>;

Fill Mode (Container-based sizing)

Perfect for hero sections and responsive layouts:

<div style={{ position: "relative", width: "100%", height: "50vh" }}>
  <Image
    src="/hero-image.jpg"
    alt="Hero background"
    fill
    placeholder="blur"
    priority
    style={{ objectFit: "cover" }}
  />
</div>

Responsive Images with Custom Sizes

<Image
  src="/responsive-image.jpg"
  alt="Responsive image"
  width={1200}
  height={800}
  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
  placeholder="blur"
  quality={85}
/>

Priority Loading (Above the fold)

For images that should load immediately:

<Image
  src="/hero.jpg"
  alt="Hero image"
  width={1200}
  height={600}
  priority
  placeholder="blur"
  quality={95}
/>

Custom Blur Data URL

Provide your own optimized blur placeholder:

<Image
  src="/image.jpg"
  alt="Custom blur example"
  width={600}
  height={400}
  placeholder="blur"
  blurDataURL="data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ..."
/>

⚙️ Configuration

Enable Development Warnings

Get helpful warnings during development:

import { configureImage } from "react-optimized-image";

// Enable warnings during development
if (process.env.NODE_ENV === "development") {
  configureImage({ enableWarnings: true });
}

Custom Image Loader

Integrate with your preferred CDN or image service:

import { Image, ImageLoader } from "react-optimized-image";

// Cloudinary example
const cloudinaryLoader: ImageLoader = ({ src, width, quality }) => {
  const params = ["f_auto", "c_limit", `w_${width}`, `q_${quality || "auto"}`];
  return `https://res.cloudinary.com/your-cloud/image/fetch/${params.join(
    ","
  )}/${src}`;
};

// Vercel Image Optimization example
const vercelLoader: ImageLoader = ({ src, width, quality }) => {
  return `/_vercel/image?url=${encodeURIComponent(src)}&w=${width}&q=${
    quality || 75
  }`;
};

<Image
  src="https://example.com/image.jpg"
  alt="CDN optimized image"
  width={800}
  height={600}
  loader={cloudinaryLoader}
/>;

🎨 Styling Examples

With CSS Classes

<Image
  src="/image.jpg"
  alt="Styled image"
  width={400}
  height={300}
  placeholder="blur"
  className="rounded-xl shadow-2xl hover:scale-105 transition-transform"
/>

With Inline Styles

<Image
  src="/image.jpg"
  alt="Styled image"
  width={400}
  height={300}
  placeholder="blur"
  style={{
    borderRadius: "12px",
    boxShadow: "0 25px 50px -12px rgba(0, 0, 0, 0.25)",
    transition: "transform 0.2s ease-in-out",
  }}
/>

🚀 Performance Tips

1. Always provide dimensions: Use width and height to prevent layout shift
2. Use blur placeholders: Add placeholder="blur" for better perceived performance
3. Optimize quality: Use quality={85} for the best balance of size and quality
4. Enable priority loading: Use priority for above-the-fold images
5. Leverage responsive images: Use the sizes prop for responsive layouts
6. Custom loaders: Integrate with CDNs for optimal delivery and caching

🔧 Advanced Usage

Error Handling

<Image
  src="/might-fail.jpg"
  alt="Image with error handling"
  width={400}
  height={300}
  onError={(e) => {
    console.log("Image failed to load:", e);
    // Could set fallback image here
  }}
  onLoadingComplete={(img) => {
    console.log(
      "Image loaded successfully:",
      img.naturalWidth,
      "x",
      img.naturalHeight
    );
  }}
/>

Dynamic Images

function ImageGallery({ images }) {
  return (
    <div className="grid grid-cols-3 gap-4">
      {images.map((image, index) => (
        <Image
          key={image.id}
          src={image.url}
          alt={image.description}
          width={300}
          height={200}
          placeholder="blur"
          priority={index < 3} // Priority for first 3 images
          sizes="(max-width: 768px) 100vw, 33vw"
        />
      ))}
    </div>
  );
}

🆚 Comparison with Alternatives

Feature	react-optimized-image	Next.js Image	react-image	img tag
Bundle Size	🟢 Tiny (~8kb)	🟡 Large	🟢 Small	🟢 None
Framework Dependency	🟢 React only	🔴 Next.js required	🟢 React only	🟢 None
Automatic Optimization	✅	✅	❌	❌
Blur Placeholders	✅	✅	❌	❌
TypeScript Support	✅	✅	✅	✅
Lazy Loading	✅	✅	✅	✅ (native)
Custom Loaders	✅	✅	❌	❌

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• GitHub Repository
• NPM Package
• Issues & Bug Reports
• Feature Requests

---

Made with ❤️ by Mona Aghili