next-image-fallback

next-image-fallback

Drop-in replacement for next/image with automatic fallback support.

Install

npm install next-image-fallback
# or
yarn add next-image-fallback
# or
pnpm add next-image-fallback

Usage

Basic Usage

import { NextImageFallback } from 'next-image-fallback';

export default function AvatarExample() {
  return (
    <NextImageFallback
      src="https://example.com/avatars/user-123.png"
      fallbackSrc="/images/avatar-placeholder.png"
      alt="User avatar"
      width={128}
      height={128}
    />
  );
}

Alternative Fallback (New Feature!)

When both primary and fallback images fail, you can display a beautiful CSS-based placeholder instead of a broken image icon:

import { NextImageFallback, ALTERNATIVE_FALLBACK } from 'next-image-fallback';

export default function AvatarExample() {
  return (
    <NextImageFallback
      src="https://example.com/avatars/user-123.png"
      fallbackSrc="/images/avatar-placeholder.png"
      alt="User avatar"
      width={128}
      height={128}
      // Alternative fallback options
      alternativeFallback="gradient"  // 'gradient' | 'waves' | 'mono'
      primaryAltColor="#6366f1"       // Primary color (hex, rgb, or named)
      secondaryAltColor="#8b5cf6"     // Secondary color for gradient/waves
      altErrorMessage="Image unavailable"  // Custom error message
      altTextColor="#ffffff"          // Text color
      onAlternativeFallback={() => console.log('Showing placeholder')}
    />
  );
}

Using Constants

import { NextImageFallback, ALTERNATIVE_FALLBACK } from 'next-image-fallback';

// Use predefined constants
<NextImageFallback
  src="/image.png"
  alt="test"
  width={200}
  height={200}
  alternativeFallback={ALTERNATIVE_FALLBACK.GRADIENT}  // or WAVES, MONO
/>

Alternative Fallback Types

Type	Description
gradient	Smooth diagonal gradient from primary to secondary color
waves	Multi-layered radial gradient creating a wave-like effect
mono	Solid single-color background using primary color

Custom Color Examples

// Using hex colors
<NextImageFallback
  src="/image.png"
  alt="test"
  width={200}
  height={200}
  alternativeFallback="gradient"
  primaryAltColor="#ff6b6b"
  secondaryAltColor="#4ecdc4"
/>

// Using RGB colors
<NextImageFallback
  src="/image.png"
  alt="test"
  width={200}
  height={200}
  alternativeFallback="waves"
  primaryAltColor="rgb(99, 102, 241)"
  secondaryAltColor="rgb(139, 92, 246)"
/>

// Using named colors
<NextImageFallback
  src="/image.png"
  alt="test"
  width={200}
  height={200}
  alternativeFallback="mono"
  primaryAltColor="slategray"
/>

Props

Standard Props

• All standard next/image props are supported (ImageProps).

Fallback Props

Prop	Type	Default	Description
fallbackSrc	ImageProps['src']	-	Alternative image to display when the primary one fails
onFallback	() => void	-	Callback fired exactly once when switching to the fallback source

Alternative Fallback Props

Prop	Type	Default	Description
alternativeFallback	'gradient' | 'waves' | 'mono'	-	Placeholder type to display when both images fail
primaryAltColor	string	'#6366f1'	Primary color (supports hex, rgb, or named colors)
secondaryAltColor	string	'#8b5cf6'	Secondary color for gradient/waves
altErrorMessage	string	'Image unavailable'	Custom error message displayed on placeholder
altTextColor	string	'#ffffff'	Text color for the error message
onAlternativeFallback	() => void	-	Callback fired when the alternative fallback is shown

How it works

• The component keeps an internal currentSrc state starting with src.
• On load error it switches to fallbackSrc (if provided and not already used) and calls onFallback.
• Also checks naturalWidth === 0 in onLoadingComplete for environments where broken images still trigger completion.
• User-supplied onError and onLoadingComplete handlers are invoked as well.
• If both original and fallback fail, it will not loop; the fallback is attempted only once per src change.
• New: When alternativeFallback is set and both images fail, a CSS-based placeholder is rendered with customizable colors and error message.

Why?

next/image does not support fallbacks out of the box. Handling onError manually across a codebase is noisy, and broken image URLs are common in user-generated content or expired remote assets. next-image-fallback provides a lightweight, reusable wrapper so you can add a single fallbackSrc prop and move on.

New: The alternative fallback feature ensures users never see ugly broken image icons – they see a beautiful, branded placeholder instead.

Next.js support (App Router & Pages Router)

The component works in both App Router and Pages Router projects on Next.js 13+. It simply wraps next/image, so static imports, remote patterns configured in next.config.js, width/height, and fill all work as usual.

Server rendering is unaffected; fallback logic only runs in the browser once the image loads or errors.

Limitations

• The fallback is attempted only once per src change to avoid infinite loops.
• Image optimization rules from your next.config.js still apply; ensure the fallback source is allowed (static asset, public folder, or configured remote).
• This package targets React 18+ and Next.js 13+.
• The alternative fallback placeholder uses CSS, so it won't work in contexts where CSS is not supported.

TypeScript Support

The package is fully typed. Import types as needed:

import type { 
  NextImageFallbackProps, 
  AlternativeFallbackType 
} from 'next-image-fallback';

Developed by

nipunarambukkanage

License

MIT © 2025 Nipuna Rambukkanage