How to Handle Missing Images — Use a Placeholder as a Fallback

Broken images — blank boxes with a small torn icon — are one of the most common visual bugs on websites. They happen when a product is deleted, a CDN URL changes, or an asset is missing from the server. The fix is a single-line fallback: if the image fails to load, swap in a placeholder. Our free placeholder generator creates that fallback image at exactly the right size. Here are the patterns to implement it.

The HTML onerror Fallback — One Line Fix for Any Image

Plain HTML img tags have a built-in error event. The simplest fallback uses the onerror attribute:

<img src="/images/product.jpg" onerror="this.src='/images/placeholder.png'; this.onerror=null;" alt="Product image">

When the browser cannot load product.jpg, it fires the error event. The onerror handler immediately replaces the src with your placeholder. The this.onerror=null line prevents an infinite loop — if the placeholder itself fails to load, the error handler is cleared so the browser does not keep retrying.

This works in every browser without any JavaScript library. It is the fastest way to fix broken images across an existing site — you can add it globally with a short script that attaches onerror handlers to all img tags on the page.

The CSS Approach — Hide Broken Images Without JavaScript

If you prefer a pure CSS solution, you can use the broken-image pseudo-elements to style the error state. However, the img element does not have consistent pseudo-element support across browsers for this purpose.

A more reliable CSS-only approach uses the img element's natural behavior when broken — it shows its alt text. Combine this with explicit sizing and a background color:

img {
  width: 400px;
  height: 300px;
  object-fit: cover;
  background-color: #cccccc;
  color: transparent; /* hides alt text by default */
}

img[alt]:not([alt=""]):not(:not([src])) {
  color: #666; /* shows alt text only when broken */
}

This keeps the layout from collapsing when an image fails, filling the space with your background color. Generate a placeholder in that exact color for a seamless fallback appearance.

Sell Custom Apparel — We Handle Printing & Free Shipping

React and Next.js — Image Error Fallback Patterns

React: Use the onError prop on the img element to trigger a state change that swaps in the placeholder:

const [imgSrc, setImgSrc] = React.useState(product.imageUrl);

<img
  src={imgSrc}
  onError={() => setImgSrc('/images/placeholder.png')}
  alt="Product"
/>

Next.js Image component: The built-in Image component accepts an onError prop with the same pattern. For the placeholder parameter, pass a data URL from our generator to show a low-quality blur while the primary image loads.

For apps with many image components, a custom hook that handles loading and error states centrally is cleaner than repeating the fallback logic in every component. See our guide to framework placeholders for hook-based patterns.

What Placeholder Image Works Best as a Fallback?

The best fallback placeholder has these properties:

• Same dimensions as the expected image: Prevents layout shift when the fallback loads. A product image container expecting 400x400 should get a 400x400 placeholder.
• Neutral but not invisible: A solid gray or light-brand-color background signals "image unavailable" without breaking the visual design of the page.
• Fast to load: Small file size means the fallback appears quickly even on slow connections. A simple solid-color PNG is typically under 2KB.
• Self-hosted: Host the placeholder on your own server, not an external service. If the original image failed due to a network issue, an external placeholder will likely fail too.

Generate your fallback PNG using our tool, download it, and upload it to the same server or CDN that hosts your other assets. See also: placeholder image URL patterns for development.

Frequently Asked Questions

Will the onerror fallback cause infinite loops if the placeholder image also fails?

Not if you include this.onerror=null in the handler. That line clears the error handler after the first fallback attempt, so the browser stops retrying if the placeholder also fails.

Can I use a data URL as the fallback source?

Yes. A data URL never returns a 404 because it is embedded in the HTML — it makes an ideal fallback. Copy a data URL from our generator and use it as the onerror replacement src.

What is the best background color for a fallback placeholder?

Match the background of the image container in your design. Light gray (#cccccc or #e0e0e0) is the most neutral choice and works on both light and dark themes.

How do I apply the onerror fallback to all images on a page automatically?

Add a short JavaScript snippet that loops through all img elements after the page loads and attaches the onerror handler. This is cleaner than adding onerror inline to every img tag in your HTML.