Axiom

System & logic

Graceful degradation

Always show a fallback when assets fail to load (broken images, failed API calls). Never show a broken state.

TagsError handlingImagesAsync
Do

Placeholder image + retry option

Don't

Broken image icon / blank screen

How to apply it

  1. 1

    Reserve the space before the request resolves, with aspect-ratio or a fixed box, so a failure cannot shift the layout.

  2. 2

    Handle the image onError by swapping in a placeholder; never let it fall through to the browser glyph.

  3. 3

    Give failed fetches a fallback state with a labelled retry that re-requests only the resource that failed.

  4. 4

    Test degraded states deliberately: block the image host and the API in devtools and walk the page.

Why it works

A failed request is a normal event, not an exception, and the browser's default handling of one is hostile: an img that 404s collapses to its alt box, so everything below it jumps up the page. Rendering a placeholder at the same dimensions, with a retry, holds the layout still and keeps the failure legible as a failure rather than as a page that looks half-built.

What breaks

One CDN hiccup and a grid of product cards shows broken-image glyphs at assorted sizes while the rows reflow around each failure, so the page reads as broken rather than as temporarily missing a few pictures.

Review questions

  1. 1

    Does a failed image show a placeholder at the same size, with nothing below it moving?

  2. 2

    Is there any raw broken-image glyph or blank gap left on the page?

  3. 3

    Can the user retry the failed request without reloading the whole page?

Related rules