Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

HTMLImageElement: image loading, dimensions, and complete state

HTMLImageElement lets you set an image source and alternative text, handle load and error events, and read natural dimensions. The complete property does not prove success: it is also true for a broken image or an element without a source.

Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntax

const image = new Image();
image.alt = description;
image.addEventListener("load", onLoad, { once: true });
image.addEventListener("error", onError, { once: true });
image.src = url;
// Read: image.naturalWidth, image.naturalHeight, image.complete

HTMLImageElement represents an image element; new Image() creates one without attaching it to the document. HTMLImageElement.src sets the resource URL, and HTMLImageElement.alt sets alternative text. Provide a meaningful description for an informative image; use an empty alt for a decorative image.

HTMLImageElement.load and HTMLImageElement.error here denote the load and error events, not callable methods. The former signals successful loading; the latter signals a loading or rendering failure. Register both listeners with addEventListener before assigning src so that a fast load cannot finish before registration.

The read-only properties HTMLImageElement.naturalWidth and HTMLImageElement.naturalHeight report density-corrected intrinsic dimensions in CSS pixels, not the size imposed by styles. An unavailable dimension is 0. HTMLImageElement.complete is read-only: it can be true after success, after failure, without a source, or with an empty src. Thus, complete alone does not prove success.

For an existing element, register both listeners first, then inspect its current state. If the element has no source, handle that case separately, but remember that an enclosing picture can supply a source. If the element has a source and complete is false, wait for load or error. The condition complete && naturalWidth > 0 does not prove that loading succeeded. An img with neither its own src nor srcset can report complete as true while the image supplied by an enclosing picture is still loading. naturalWidth can become positive as soon as the dimensions are available, before loading finishes. If complete && naturalWidth === 0, these properties still do not tell you the outcome: an image without an intrinsic width can load successfully. Do not treat it as unavailable on that basis. If you recorded a load or error outcome for the current image request, use it. A newly registered listener will not receive an event that already fired. Make sure the state check and the event listeners cannot handle the same result twice.

This is a browser API defined by HTML, not a feature of a particular ECMAScript edition. The basic mechanisms described here are widely supported; Node 24 in a repository does not prove browser API availability. The example creates a decorative SVG image in memory without attaching it to the document. The SVG has an explicit positive width and height, so the example does not show a successful load without an intrinsic width.

Examples

(() => {
  const image = new Image();
  image.alt = "";

  image.addEventListener("load", () => {
    console.log(`load: ${image.naturalWidth}x${image.naturalHeight}; complete=${image.complete}`);
  }, { once: true });

  image.addEventListener("error", () => {
    console.log("error: image unavailable");
  }, { once: true });

  const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="2" height="3"><rect width="2" height="3" fill="blue"/></svg>';
  image.src = `data:image/svg+xml,${encodeURIComponent(svg)}`;
})();

Result

load: 2x3; complete=true

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources