Plainform

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

@/components/UserAvatar.tsx

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:

@/components/Hero.tsx

<ImageWithFallback
  src="/hero-image.jpg"
  alt="Hero banner"
  width={1200}
  height={600}
  priority
  quality={90}
/>

Dynamic Image Lists

@/components/Gallery.tsx

{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

Error Handling

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:

Custom Fallback

import Fallback from '@/public/custom-placeholder.png';

Responsive Images

Responsive Sizing

<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

@/components/UserMenu.tsx

<ImageWithFallback
  src={user.imageUrl}
  alt={user.name}
  width={40}
  height={40}
  className="rounded-full ring-2 ring-border"
/>

Product Images

@/components/ProductGrid.tsx

<ImageWithFallback
  src={product.imageUrl}
  alt={product.name}
  width={300}
  height={300}
  className="aspect-square object-cover rounded-lg"
/>

Customer Testimonials

@/components/TotalBuyers.tsx

{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:

Quality Settings

{/* 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.

Next.js Image - Official documentation
TotalBuyers.tsx - Uses this component

ImageWithFallback.tsx

On this page