ImageWithFallback.tsx
A Next.js Image wrapper component that automatically displays a fallback image when the source fails to load.
The ImageWithFallback component wraps Next.js Image with automatic fallback handling. It displays a placeholder image when the source is empty, null, or fails to load, preventing broken image displays.
Props
| ImageWithFallback Props | Type | Default |
|---|---|---|
src | string | - |
alt | string | - |
width? | number | - |
height? | number | - |
sizes? | string | - |
className? | string | - |
quality? | number | 75 |
priority? | boolean | false |
Usage
Basic Implementation
import { ImageWithFallback } from '@/components/ImageWithFallback';
export function UserAvatar({ user }) {
return (
<ImageWithFallback
src={user.avatarUrl}
alt={user.name}
width={48}
height={48}
className="rounded-full"
/>
);
}With Priority Loading
For above-the-fold images:
<ImageWithFallback
src="/hero-image.jpg"
alt="Hero banner"
width={1200}
height={600}
priority
quality={90}
/>Dynamic Image Lists
{images.map((image, index) => (
<ImageWithFallback
key={index}
src={image.url}
alt={image.alt}
width={400}
height={300}
className="object-cover rounded-md"
/>
))}Features
- Automatic Fallback: Displays placeholder when source fails or is empty
- Error Recovery: Catches image load errors automatically
- Source Change Detection: Resets error state when source changes
- Next.js Optimization: Inherits all Next.js Image optimizations
- Type Safety: Full TypeScript support
Implementation Details
Fallback Logic
const imageSrc = !src || error ? Fallback : src;Shows fallback if source is empty or image fails to load.
Error State Management
const [error, setError] = useState<boolean | null>(null);
// Reset error when source changes
useEffect(() => {
setError(null);
}, [src]);
// Set error on load failure
<Image onError={() => setError(true)} src={imageSrc} {...props} />Customization
Custom Fallback Image
Replace the default placeholder in @/components/ImageWithFallback.tsx:
import Fallback from '@/public/custom-placeholder.png';Responsive Images
<ImageWithFallback
src={imageUrl}
alt="Responsive image"
width={800}
height={600}
sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
/>Common Use Cases
User Avatars
<ImageWithFallback
src={user.imageUrl}
alt={user.name}
width={40}
height={40}
className="rounded-full ring-2 ring-border"
/>Product Images
<ImageWithFallback
src={product.imageUrl}
alt={product.name}
width={300}
height={300}
className="aspect-square object-cover rounded-lg"
/>Customer Testimonials
{customers.map((customer, i) => (
<ImageWithFallback
key={i}
src={customer.imageUrl}
alt={customer.name}
width={48}
height={48}
className="rounded-full ring-4 ring-background"
/>
))}Performance
Use priority for above-the-fold images and adjust quality based on use case:
{/* Hero images */}
<ImageWithFallback src={hero} quality={90} priority {...props} />
{/* Thumbnails */}
<ImageWithFallback src={thumb} quality={75} {...props} />Client Component
This is a client component ('use client') because it uses useState, useEffect, and onError event handler.
Related
- Next.js Image - Official documentation
- TotalBuyers.tsx - Uses this component
How is this guide ?
Last updated on