zenui-image-react

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

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

License

MIT © Asfak Ahmed ( rahi )