v152 · html · images

When the browser changes your picture

Browsers are starting to modify media on the user's behalf — a virtual try-on, a generated variation, a substitution the user asked for. The page keeps rendering everything it built around that image: a zoom lens over pixels that are no longer there, a caption describing a garment nobody is now wearing. Two events and a property let the page notice and adapt.

concepts

  1. The three things it adds

    Two events and one read-only property on HTMLImageElement. Probed here member by member, with controls that prove the probe would find them if they were present.

  2. A product page that adapts

    The explainer's own example, built and working: a zoom lens that hides while the image is replaced. The listeners are real and the replacement is simulated — clearly, and only where no other option exists.

  3. What breaks without them

    An inventory of the page furniture that becomes wrong the moment an image is not the image you shipped — and which of it a page can already detect by other means, which turns out to be almost none.

why it shipped

A page is not just an image; it is an image plus everything arranged around it. Zoom controls assume the pixels are the ones the server sent. A colour swatch assumes the photograph shows that colour. Alt text describes what was there. A "report this listing" link means something specific about the seller's photograph.

When a browser feature replaces the image at the user's request, all of that stays on screen and stops being true. The proposal's answer is deliberately small: tell the page it happened, and let it decide. No opt-out is proposed — the explainer defers author hints to future work — so what a page gets is the chance to adapt rather than a veto.

the API

image.addEventListener("uareplacestart", () => {
  zoomLens.hidden = true;                 // the pixels are no longer yours
  caption.textContent = "Showing a browser-provided variation";
});

image.addEventListener("uareplaceend", () => {
  zoomLens.hidden = false;
});

// Read the current state at any time.
if (image.replacedByUserAgent) { /* … */ }

The uareplaceend event fires when the substitution finishes, fails, or is reverted — three outcomes on one event, so a handler that assumes it means "back to normal" will be wrong a third of the time.

enabling it now

Not available on the Chrome 152-era build these pages were made with, with or without a flag. Measured: "replacedByUserAgent" in document.createElement("img") is false, and no property matching /replace|ua/i exists on HTMLImageElement.prototype.

Object.getOwnPropertyNames(HTMLImageElement.prototype)
  .filter((n) => /replace|ua/i.test(n))
// []

So the adaptation demo simulates the replacement, and says so on the page rather than only here — the listeners it attaches are real, and would be woken by a real event without a line changing.

references