How to Style Broken Images Without JavaScript

CSS can make broken images less disruptive by preserving space and styling the surrounding box. It cannot guarantee the same error icon or visible alt-text treatment in every browser.

For an article image, useful alternative text and predictable dimensions matter more than a custom failure graphic. A missing photograph should leave the article readable, even if the browser’s fallback looks rather ordinary.

Style broken images with a stable base

Start with dimensions and a description that would make sense without the picture:

<img
  class="article-image"
  src="/photos/riga-street.webp"
  width="1200"
  height="800"
  alt="A tram passing wooden houses on a Riga street"
>

.article-image {
  display: block;
  max-width: 100%;
  height: auto;
  background: #f3f3f3;
  color: #444;
  font: 0.875rem/1.4 system-ui, sans-serif;
}

The image element reference explains how width and height establish an aspect ratio before the resource loads. Those attributes also help the normal loading state avoid an unnecessary layout shift.

The background belongs to the image box whether the request succeeds or fails. It is a base style, rather than an error detector, and the browser still decides how to present a failed image.

Keep these rules scoped to content images. Applying a background and large text styles to every image can produce odd results on icons and small decorative assets.

Write the description for the image’s purpose

Alternative text should communicate the image’s contribution to the page. A filename such as IMG_4028 rarely helps a reader understand what is missing.

The HTML guidance on text alternatives makes the image’s context part of that decision. A diagram may need its important explanation in nearby prose; a decorative flourish can use an empty alternative:

<img src="/decoration.svg" alt="">

Do not add a description merely to give a broken decorative image something to display. Decoration can remain silent, while information needs an equivalent the reader can actually use.

Keep informative pictures in HTML rather than moving them into CSS backgrounds to avoid the broken-image icon. A background image does not provide an image element’s alternative text. Backgrounds suit decoration; content still needs a meaningful equivalent when the asset is unavailable.

Give card media its own dimensions

A card may need a consistent media area even when the image cannot provide its natural size. Put that layout decision on a wrapper:

<figure class="card-media">
  <div class="card-media__frame">
    <img
      src="/photos/riga-street.webp"
      width="1200"
      height="800"
      alt="A tram passing wooden houses on a Riga street"
    >
  </div>
  <figcaption>Tram routes through Riga's older neighbourhoods</figcaption>
</figure>

.card-media {
  margin: 0;
}

.card-media__frame {
  aspect-ratio: 16 / 9;
  background: #f3f3f3;
}

.card-media__frame img {
  display: block;
  width: 100%;
  height: 100%;
  object-fit: cover;
}

The wrapper’s aspect-ratio reserves the media shape independently of the request. The image fills that box, and object-fit: cover crops a successfully loaded picture when its proportions differ.

That cropping is a deliberate thumbnail policy. For an instructional screenshot, cutting off the edge may remove the exact detail the reader needs; keep natural proportions there instead.

The caption stays outside the media frame. It can provide context even when the picture fails, without depending on how much alt text fits inside the image box.

CSS does not give you an image-error selector

An attribute selector can match a URL, and :has(img) can check whether an image element exists. Neither tells you whether the image request succeeded.

The image loading-error documentation describes the error event for script-based handling. A retry action or a reliably substituted asset needs that additional behaviour, or a decision made before sending the HTML.

Pseudo-element tricks on the image itself also make a poor foundation for essential fallback text. Keep the important explanation in HTML, where it does not depend on the browser’s internal error presentation.

Check failure alongside successful loading

During development, replace a source with a deliberately missing URL and compare the result with the working image. Check a narrow card as well as a wide article layout, especially if the description is long.

Look for collapsed space or clipped descriptions. Check whether the caption still makes sense when the picture is unavailable.

Defensive CSS for unexpected content follows the same principle: decide what the layout should tolerate. For a missing image, a stable frame and useful surrounding text are usually a better starting point than another decorative icon.

← Back to all articles