@philiprehberger/next-image-components

Next.js Image wrappers with skeleton loading, blur-up placeholders, and error fallback

Installation

npm install @philiprehberger/next-image-components clsx

Usage

import { OptimizedImage } from '@philiprehberger/next-image-components';

<OptimizedImage
  src="/photos/hero.jpg"
  alt="Hero image"
  width={800}
  height={400}
/>

Skeleton + error fallback

import { OptimizedImage } from '@philiprehberger/next-image-components';

<OptimizedImage
  src="/photos/hero.jpg"
  alt="Hero image"
  width={800}
  height={400}
  fallbackSrc="/images/placeholder.svg"
/>

Blur-up placeholder

Provide a base64 data URL via blurDataURL to render a low-resolution preview while the full image loads. The skeleton overlay is suppressed automatically when a blur preview is supplied.

import { OptimizedImage } from '@philiprehberger/next-image-components';

<OptimizedImage
  src="/photos/hero.jpg"
  alt="Hero image"
  width={800}
  height={400}
  blurDataURL="data:image/jpeg;base64,/9j/4AAQSkZJRg..."
/>

To force the skeleton on top of the blur, pass showSkeleton:

<OptimizedImage
  src="/photos/hero.jpg"
  alt="Hero image"
  width={800}
  height={400}
  blurDataURL="data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  showSkeleton
/>

API

OptimizedImage

Drop-in replacement for next/image with skeleton, blur-up, fade-in, and error fallback.

Prop	Type	Default	Description
src	ImageProps['src']	required	Source URL or imported image
alt	string	required	Alt text for the image
fallbackSrc	string	/images/placeholder.svg	Image to render when the primary src fails
showSkeleton	boolean	true (no blur) / false (with blur)	Show a pulse skeleton while loading
containerClassName	string	undefined	CSS class on the outer wrapping div
blurDataURL	string	undefined	Base64 data URL used as a blur-up placeholder
placeholder	'blur' | 'empty' | string	'blur' if blurDataURL is set, else inherited from next/image	Override next/image's placeholder mode
...rest	ImageProps	—	Any other prop accepted by next/image

Development

npm install
npm run build
npm test

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT