Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

Natural image dimensions and the `complete` state

Read an image’s natural size in CSS pixels and distinguish request completion from successful loading or decoding.

Version: ECMAScript 2024 and the current web platform; runtime support varies

Syntax

img.naturalWidth  // number: natural width
img.naturalHeight // number: natural height
img.complete      // boolean: completion state, not success

HTMLImageElement.naturalWidth/naturalHeight/complete refers to three read-only properties on an image element. naturalWidth and naturalHeight give the current image’s natural width and height as integers in CSS pixels. They account for the selected resource’s pixel density and metadata orientation, so they need not match the dimensions stored in the file. On a rendered element, width and height instead describe its size on the page.

When the current image’s dimensions are not yet available, both natural dimension properties return 0. The dimensions can become known before the download finishes, so positive values do not prove the whole image has loaded or decoded. Check that both dimensions are positive before calculating img.naturalWidth / img.naturalHeight.

complete returns a Boolean. It is true if both src and srcset are absent, or if src is empty and srcset is absent. It is also true if the current request is fully available or broken and no replacement request is pending. Otherwise it is false. This is a snapshot, not a success flag.

Register load and error handlers before setting src to distinguish success from failure. If you need the image decoded, use await img.decode() after setting the source and handle rejection. These are browser Web APIs, not core ECMAScript features.

Examples

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Natural image dimensions and completion</title>
</head>
<body>
<script>
(async () => {
  function report(label, img) {
    console.log(`${label}: ${img.complete} ${img.naturalWidth} ${img.naturalHeight}`);
  }

  async function inspect(src) {
    const img = new Image();
    const eventType = await new Promise((resolve) => {
      img.onload = img.onerror = (event) => resolve(event.type);
      img.src = src;
    });
    report(eventType, img);
  }

  const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="16"><rect width="24" height="16"/></svg>';
  report('no source', new Image());
  await inspect('data:image/svg+xml,' + encodeURIComponent(svg));
  await inspect('data:image/svg+xml,not-an-svg');
})();
</script>
</body>
</html>

Result

no source: true 0 0
load: true 24 16
error: true 0 0

The three lines show an image with no source, a valid 24 × 16 SVG, and an invalid SVG. All three report `complete` as `true`. Open the HTML file in a browser with image loading enabled and `data:` images allowed, then check the developer console.

Related lessons

  • JavaScript · Lesson 33 · Advanced · Version: 4

Sources