https://github.com/zenui-labs/zenui-image-react
Render responsive images with lazy loading and optimized performance using customizable placeholders and skeletons.
https://github.com/zenui-labs/zenui-image-react
lazy-image lazy-loading lazy-loading-components loading npm npm-package optimize-image placeholder react
Last synced: 4 months ago
JSON representation
Render responsive images with lazy loading and optimized performance using customizable placeholders and skeletons.
- Host: GitHub
- URL: https://github.com/zenui-labs/zenui-image-react
- Owner: zenui-labs
- License: mit
- Created: 2025-01-16T17:15:02.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-01-17T13:31:23.000Z (over 1 year ago)
- Last Synced: 2025-09-09T23:48:55.086Z (10 months ago)
- Topics: lazy-image, lazy-loading, lazy-loading-components, loading, npm, npm-package, optimize-image, placeholder, react
- Language: JavaScript
- Homepage: https://zenui.net/zenui-image-react-playground
- Size: 120 KB
- Stars: 35
- Watchers: 1
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://zenui.net/zenui-image-react-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**](https://github.com/Asfak00/zenui-image-react)
## Installation
```bash
npm install zenui-image-react
```
## Basic Usage
```jsx
import { LazyLoadImage } from 'zenui-image-react';
function MyComponent() {
return (
);
}
```
## Advanced Features
### 1. Placeholder Types
Choose from multiple placeholder types while your image loads:
```jsx
// Effect Placeholder (blur, opacity, or color)
// Custom Image Placeholder
// Custom Component Placeholder
}
/>
```
### 2. Image Optimization
Enable automatic responsive image optimization:
```jsx
```
### 3. Custom Loading Behavior
Control the intersection observer and loading offset:
```jsx
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
```javascript
{
xs: 320,
sm: 576,
md: 768,
lg: 992,
xl: 1200,
xxl: 1400
}
```
### Default Image Widths
```javascript
{
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 )