Image Resilience

Overview

When an image fails to load — whether from a broken path, missing asset, or network error — the theme automatically swaps it with a configurable placeholder image. This prevents broken-image icons from appearing in the rendered page.

The feature is enabled by default and requires no setup to work. The core ships a neutral placeholder; sites can override it with a branded alternative.

Who this is for

• Implementors configuring the fallback placeholder image for a client site
• Editors understanding why broken images show a placeholder instead of a broken-image icon

How it works

A global error handler listens for image load failures across the entire page. When a failure is detected, the handler:

1. Replaces the broken image’s src with the configured fallback image
2. Replaces the alt text with the configured fallback alt text
3. Marks the element with data-fallback-applied to prevent repeated swaps

The handler uses capture-phase event delegation on document, so it covers all <img> elements regardless of which component rendered them — section components, markdown body images, and plain HTML images are all covered.

Site configuration

The fallback image is configured in site.ts via the imageFallback field:

import placeholderImg from "@site/assets/images/placeholder.png?url";

export const siteConfig: SiteConfig = {
  ...DEFAULT_SITE_CONFIG,

  imageFallback: {
    ...DEFAULT_SITE_CONFIG.imageFallback,
    src: placeholderImg,
    alt: "Image currently unavailable",
  },
};

The ?url import suffix resolves the asset through Vite’s pipeline, producing a hashed URL in the production build.

Disabling the feature

To disable image resilience entirely:

imageFallback: {
  ...DEFAULT_SITE_CONFIG.imageFallback,
  enabled: false,
},

When disabled, no error listener is registered and broken images receive no fallback treatment.

Opting out per-component

Components that manage their own image error handling can opt out by adding the data-no-fallback attribute to their <img> elements:

<img src="{src}" alt="{alt}" data-no-fallback />

The global handler skips any element with this attribute. Two core components use it:

• SiteLogo — manages its own fallback chain (text rendering) and uses vanilla JS reactive src binding for theme-aware logo swapping
• YouTubeEmbed — poster thumbnails are third-party assets whose failure is better handled by the embed’s click-to-load UI

Infinite-loop guard

If the fallback image itself fails to load, the handler does not retry. The data-fallback-applied attribute is set before the src swap, so a second error event on the same element is ignored. This prevents infinite error-swap cycles.

Styling replaced images

The data-fallback-applied attribute can be used as a CSS selector to style images that were replaced by the fallback:

img[data-fallback-applied] {
  opacity: 0.6;
}