react-use-optimized-image/README.md

A React hook for image optimization (format detection, lazy loading, caching, CDN support)

# 🚀 React Use Optimized Image

A smart **image optimization hook** for React that improves performance by **auto-detecting formats, lazy loading, caching, and optimizing based on network speed**. 🎯

![npm](https://img.shields.io/npm/v/react-use-optimized-image?color=blue&style=flat-square)
![npm downloads](https://img.shields.io/npm/dt/react-use-optimized-image?color=green&style=flat-square)
![MIT License](https://img.shields.io/npm/l/react-use-optimized-image?color=orange&style=flat-square)

---

## 📦 **Installation**

```sh
npm install react-use-optimized-image
# or
yarn add react-use-optimized-image
```

## 🌟 **Features & Benefits**

### ✅ **Automatic Format Detection**

- Uses **WebP / AVIF** for supported browsers for better compression.
- Falls back to **JPEG / PNG** for older browsers.
- Saves bandwidth & improves **Core Web Vitals (LCP, FCP).**

### 🚀 **Lazy Loading for Faster Performance**

- Uses **`IntersectionObserver`** to load images only when visible.
- Reduces **initial page load time** and improves SEO.

### 💾 **Smart Caching with Local Storage**

- Stores **optimized image URLs** in `localStorage` for **instant reloads**.
- Reduces **redundant requests**, making browsing faster.

### ⚡ **Network Speed Adaptation**

- Uses **`navigator.connection.effectiveType`** to adjust image quality:
  - **Fast network** → Loads high-resolution images.
  - **Slow network (2G/3G)** → Loads compressed images to improve speed.

### 🌍 **CDN Support for Global Access**

- Supports **Cloudinary, Imgix, and other CDNs**.
- Ensures **faster load times** for users worldwide.

### 🔧 **Developer-Friendly API**

- Simple **React hook-based API** with **TypeScript support**.
- Fully customizable with **format, quality, and lazy load options**.

---

# 🛠 Usage Examples (JSX)

## 📌 Basic JSX Example

```jsx
import React from "react";
import { useOptimizedImage } from "react-use-optimized-image";

const ImageComponent = () => {
  const { optimizedSrc, isLoading, imgRef } = useOptimizedImage({
    src: "https://example.com/image.jpg",
    lazy: true,
  });

  return (
    <div>
      {isLoading ? (
        <p>Loading...</p>
      ) : (
        <img ref={imgRef} src={optimizedSrc} alt="Optimized" />
      )}
    </div>
  );
};

export default ImageComponent;
```

## 📌 TypeScript Example with Custom Props

```tsx
import React from "react";
import { useOptimizedImage } from "react-use-optimized-image";

interface ImageProps {
  src: string;
  alt: string;
  quality?: number;
}

const OptimizedImage: React.FC<ImageProps> = ({ src, alt, quality = 80 }) => {
  const { optimizedSrc, isLoading, imgRef } = useOptimizedImage({
    src,
    quality,
  });

  return (
    <div>
      {isLoading ? (
        <p>Loading...</p>
      ) : (
        <img ref={imgRef} src={optimizedSrc!} alt={alt} />
      )}
    </div>
  );
};

export default OptimizedImage;
```

# 🔥 Advanced Use Cases

## 1️⃣ Optimizing Images with CDN

```jsx
const { optimizedSrc } = useOptimizedImage({
  src: "https://res.cloudinary.com/demo/image/upload/sample.jpg",
  quality: 80,
  cdn: "cloudinary",
});
```

✅ Automatically formats URL for better compression & performance.

## 2️⃣ Caching for Faster Reloads

```jsx
const { optimizedSrc } = useOptimizedImage({
  src: "https://example.com/image.jpg",
  cache: true,
});
```

✅ Minimizes redundant API calls, reducing server load.

## 3️⃣ Adaptive Quality Based on Network Speed

```jsx
const { optimizedSrc } = useOptimizedImage({
  src: "https://example.com/image.jpg",
  adjustForNetwork: true,
});
```

✅ Ensures fast loading for all users, even on mobile networks.