Blog Implementation January 26, 2026 13 min read

From Broken Image Icon to Branded Fallback: A Production Rollout Checklist

Audit broken image states, choose branded fallback URLs, update shared components, test image failures, and monitor rollout quality.

Broken image fallbackBroken image iconFallback image checklistImage fallback rollout

Replacing browser broken-image icons is a production rollout, not a one-line onerror patch.

Start with an image surface audit, then standardize fallback dimensions, labels, colors, components, accessibility behavior, testing, caching, and monitoring.

Rollout mindset

Treat broken-image icons as production defects

The browser broken-image icon is a useful signal for developers, but it is a poor product state for users. It communicates that something failed without preserving the design system or keeping repeated layouts calm.

A branded fallback rollout gives every important image slot a controlled state. The work includes product inventory, frontend implementation, accessibility, QA, performance, cache behavior, observability, and content rules.

Checklist 1

Audit every image surface

Start by listing image surfaces instead of jumping straight into code. Most apps have more image slots than one team remembers: product cards, avatars, logos, banners, article covers, file thumbnails, CMS previews, dashboards, support tools, admin pages, and emails.

For each surface, capture the owner, route, component, final dimensions, aspect ratio, source system, alt text behavior, current failure behavior, and customer impact.

Checklist 2

Choose a fallback URL for each surface type

Use fallback URLs that match the real image shape. A product square should not fall back to a wide banner. A report preview should not fall back to an avatar square.

Keep labels generic: Product Image, User, Article Image, File Preview, Report Preview, Workspace, Image Unavailable.

Implementation text

Product card:
https://fallback.pics/api/v1/800x800/F4F4F5/18181B?text=Product+Image

User avatar:
https://fallback.pics/api/v1/400x400/18181B/FFFFFF?text=User

Report preview:
https://fallback.pics/api/v1/1200x630/7C3AED/FFFFFF?text=Report+Preview

Checklist 3

Reserve layout before images load or fail

Add width and height attributes for fixed media, or use a stable aspect-ratio container for responsive surfaces. The fallback should not introduce a second layout shift after the original image fails.

Check card grids, dashboard rows, modals, side panels, and mobile breakpoints. A fallback rollout is incomplete if it works only on the happy-path desktop layout.

Implementation text

<img
  src="/media/products/example.jpg"
  width="800"
  height="800"
  alt="Product image"
  onerror="this.onerror=null;this.src='https://fallback.pics/api/v1/800x800/F4F4F5/18181B?text=Product+Image'"
/>

Checklist 4

Move fallback behavior into shared components

One-off onerror handlers are useful for quick fixes, but production rollouts need shared image primitives. The component should handle missing source data, failed loads, dimensions, alt text, and safe fallback labels.

A shared component also gives design, QA, and engineering one place to update fallback color, text, and dimensions.

Implementation tsx

const fallbackForSurface = {
  product: 'https://fallback.pics/api/v1/800x800/F4F4F5/18181B?text=Product+Image',
  avatar: 'https://fallback.pics/api/v1/avatar/128/18181B/FFFFFF?text=User',
  article: 'https://fallback.pics/api/v1/1200x630/18181B/FFFFFF?text=Article+Image',
} as const;

Checklist 5

Test the failure paths deliberately

Do not wait for production media failures to validate the rollout. Create fixtures for missing URLs, empty strings, 404s, slow responses, blocked hosts, unsupported formats, and decode failures.

Use Storybook, Playwright, visual regression tests, or manual QA to verify that each fallback preserves layout and remains readable.

Privacy

Keep rollout labels public-safe

Every fallback URL used in the rollout should be safe in logs, screenshots, browser history, support tickets, and analytics. Use generic surface labels only.

Do not put secrets, emails, tokens, account IDs, order IDs, private customer values, private product values, or regulated data in placeholder URL text.

Key takeaways

What to standardize before shipping

Audit image surfaces before writing fallback code.
Choose fallback URLs that match each surface ratio and use generic public-safe labels.
Reserve image layout with width and height attributes or CSS aspect-ratio.
Move fallback behavior into shared image components.
Test missing data, failed loads, slow networks, blocked domains, and responsive layouts before rollout.

Production fallback layer