ZenUI Image React

A highly customizable, performance-focused React component for lazy loading images with advanced features like placeholder effects, image optimization, and responsive loading.

Try it with our Playground

Features

• 🎯 Lazy Loading: Load images only when they enter the viewport
• 🖼 Placeholder Support: Multiple placeholder types while images load
• 🎨 Effect Transitions: Smooth transitions with blur, opacity, or color effects
• 📱 Responsive Images: Automatic srcset and sizes generation
• ⚡ Performance Optimized: Intersection Observer for efficient lazy loading
• 🛠 Highly Customizable: Extensive props for fine-tuning behavior
• 📦 Lightweight: Small bundle size.

If our GitHub repository reaches 200 stars ⭐, we will proudly launch the Vue version of this package.

Star the Repository on GitHub

Installation

npm install zenui-image-react

Basic Usage

import { LazyLoadImage } from 'zenui-image-react';

function MyComponent() {
  return (
    <LazyLoadImage
      src="https://example.com/image.jpg"
      alt="Example"
      placeholderType="effect"
      effectType="blur"
    />
  );
}

Advanced Features

1. Placeholder Types

Choose from multiple placeholder types while your image loads:

// Effect Placeholder (blur, opacity, or color)
<LazyLoadImage
  src="image.jpg"
  placeholderType="effect"
  effectType="blur"
  effectAmount={10}
/>

// Custom Image Placeholder
<LazyLoadImage
  src="image.jpg"
  placeholderType="image"
  placeholderImage="placeholder.jpg"
/>

// Custom Component Placeholder
<LazyLoadImage
  src="image.jpg"
  placeholderType="custom"
  customPlaceholder={<MyCustomLoader />}
/>

2. Image Optimization

Enable automatic responsive image optimization:

<LazyLoadImage
  src="image.jpg"
  optimize
  quality={80}
  breakpoints={{
    sm: 576,
    md: 768,
    lg: 992,
    xl: 1200
  }}
  imageWidths={{
    sm: [576],
    md: [768],
    lg: [992],
    xl: [1200]
  }}
/>

3. Custom Loading Behavior

Control the intersection observer and loading offset:

<LazyLoadImage
  src="image.jpg"
  useIntersectionObserver={true}
  offset={200} // Start loading 200px before entering viewport
  onLoad={() => console.log('Image loaded')}
  onError={(e) => console.error('Load failed:', e)}
/>

API Reference

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | src | string | Required | Image source URL | | alt | string | '' | Alt text for the image | | className | string | '' | CSS class name | | style | object | {} | Inline styles | | placeholderType | enum | 'none' | Type of placeholder ('none', 'effect', 'image', 'custom') | | effectType | enum | 'blur' | Effect type ('blur', 'opacity', 'color') | | effectAmount | number | 10 | Intensity of the effect | | placeholderImage | string | - | URL for placeholder image | | customPlaceholder | element | - | Custom React component as placeholder | | optimize | boolean | false | Enable responsive image optimization | | quality | number | 80 | Image quality (1-100) when optimize is true | | breakpoints | object | - | Custom breakpoints for responsive loading | | imageWidths | object | - | Width configurations for each breakpoint | | sizes | string | - | Custom sizes attribute for responsive images | | useIntersectionObserver | boolean | true | Enable/disable intersection observer | | offset | number | 0 | Loading offset in pixels | | onLoad | function | - | Callback when image loads | | onError | function | - | Callback when image fails to load |

Default Breakpoints

{
  xs: 320,
  sm: 576,
  md: 768,
  lg: 992,
  xl: 1200,
  xxl: 1400
}

Default Image Widths

{
  xs: [320],
  sm: [576],
  md: [768],
  lg: [992],
  xl: [1200],
  xxl: [1400]
}

Performance Tips

1. Use WebP Format: Provide WebP images when possible for better compression
2. Optimize Image Dimensions: Use appropriate image sizes for different breakpoints
3. Enable Optimization: Use the optimize prop for automatic responsive handling
4. Adjust Loading Offset: Set an appropriate offset based on your use case
5. Choose Appropriate Quality: Balance quality and file size with the quality prop

License

MIT © Asfak Ahmed ( rahi )