HTML image decoding async: choose a hint or wait for a ready replacement

Consider a room-selection page with a small floor-plan preview. A reader chooses another room while its larger plan is still loading. Keeping the old preview until the replacement is ready avoids deliberately inserting an empty image. The displayed room label must change with the displayed plan, so it does not describe a different room during the wait.

Add the hint without changing the loading policy

<img src="./north-room.png"
     alt="North room plan with the entrance on the left"
     width="960" height="640"
     decoding="async">

Supply the named image file. async lets other content be presented without waiting for this image's decoding. sync requests presentation together with other content; auto leaves the choice to the browser. A static image may show little visible difference between these choices.

This attribute does not defer downloading until scrolling, choose a smaller file, or increase request priority. Use lazy loading for appropriate offscreen images and fetchpriority for a separate relative-priority decision. Keep the width, height, and useful alternative text whichever decoding hint you choose.

Replace the current plan after decoding

The following fragment belongs in a page that already contains #room-preview and #room-status. Call showRoomPlan() from its existing room-choice control. Each call receives the matching image URL and room description:

const preview = document.querySelector('#room-preview');
const status = document.querySelector('#room-status');
let latestPlanRequest = 0;

async function showRoomPlan(url, description) {
  const request = ++latestPlanRequest;
  status.textContent = 'Loading selected room plan…';
  const next = new Image(960, 640);
  next.alt = description;
  next.src = url;

  try {
    await next.decode();
    if (request !== latestPlanRequest) return;
    preview.replaceChildren(next);
    status.textContent = description;
  } catch {
    if (request === latestPlanRequest) {
      status.textContent = 'Plan unavailable; previous preview retained.';
    }
  }
}

The counter gives the latest choice ownership of the preview. If North starts first and South finishes first, the older North result cannot replace South afterward. It does not cancel the older download. Match the dimensions to your own assets and give the preview a responsive image rule such as max-width:100%; height:auto.

The promise can reject when the request fails, the image data is corrupt, or its source changes during decoding. Keep the displayed preview intact on failure and expose the status in the page's existing accessible feedback area. A successful decode means the image data is ready for use; it does not prove that this plan is the correct file for the selected room.

Check the last choice and the failure result

In the served page, select two rooms quickly while throttling the image responses. Confirm that the final visible plan and description both match the last selection. Then choose an unavailable URL: the previous plan should remain, with the failure message beside it.

Inspect the actual image dimensions and alternative text after replacement. Use a performance recording if you need to compare presentation timing; this pattern makes no fixed speed claim. Before sending the page for review, check the plan's room name against its visible entrance and labels so a technically successful replacement does not deliver the wrong drawing.