naturalWidth & naturalHeight: Browser Support, Use Cases

What are naturalWidth and naturalHeight?

naturalWidth and naturalHeight are read-only properties of the HTMLImageElement interface defined by the WHATWG HTML Standard. They return the intrinsic, density-corrected width and height of the image source in CSS pixels. The values are 0 until the browser finishes decoding the image data.

Which browsers support naturalWidth and naturalHeight?

naturalWidth and naturalHeight are Baseline Widely Available and ship in every modern desktop and mobile browser. Internet Explorer 9 through 11 also support both properties; IE 5.5 to 8 are the only browsers that never added them.

How do you use naturalWidth and naturalHeight in JavaScript?

Read the properties off any HTMLImageElement after the image has finished decoding. The values are valid inside a load event handler, after the boolean complete property is true, or after an awaited img.decode() call.

• Grab the element: Use document.querySelector or pass the element directly. Both DOM-attached and detached HTMLImageElement instances expose the properties.
• Wait for the load event: Attach addEventListener('load', handler). Inside the handler, naturalWidth and naturalHeight are always populated.
• Guard with the complete property: If the image is already cached, the load event has fired before your script ran. Check img.complete first and read the values immediately when it is true.
• Read the values: Both return numbers in CSS pixels. Divide naturalWidth by naturalHeight to compute the aspect ratio.
• Re-read on src changes: Setting img.src resets the values to 0. Re-attach the load handler so the layout code sees the new dimensions.

// 1. Read intrinsic size after the image element finishes loading.
const heroImg = document.querySelector('img.hero');

heroImg.addEventListener('load', () => {
    console.log('Intrinsic width:', heroImg.naturalWidth, 'CSS px');
    console.log('Intrinsic height:', heroImg.naturalHeight, 'CSS px');
});

// 2. Preload an image with the Image constructor and read its size off-DOM.
const probe = new Image();
probe.addEventListener('load', () => {
    const aspectRatio = probe.naturalWidth / probe.naturalHeight;
    console.log('Aspect ratio:', aspectRatio.toFixed(3));
});
probe.src = '/static/banner.jpg';

// 3. Guard against the not-yet-loaded case before reading the value.
function getIntrinsicSize(img) {
    if (img.complete && img.naturalWidth > 0) {
        return { width: img.naturalWidth, height: img.naturalHeight };
    }
    return null;
}

What is the difference between naturalWidth and width?

naturalWidth and width look interchangeable but they answer different questions. naturalWidth describes the source asset; width describes how the asset is rendered on the page. Same story for naturalHeight versus height.

What are the common pitfalls of naturalWidth and naturalHeight?

Cross-browser support is solid, but the value is empty in more situations than authors expect. Most production bugs trace back to reading the property too early, mis-handling SVGs, or forgetting that the src reset clears the cached value.

• Reading before the image decodes: The most frequent failure. naturalWidth is 0 until the load event fires. Code that runs in the parser or in a synchronous callback after setting src reads 0 in every browser.
• SVG with viewBox only: Chrome, Firefox, and Safari return 0 for an SVG that has a viewBox but no width and height attributes on the root element. Add explicit width and height to the SVG, or measure with getBoundingClientRect on the rendered element.
• Cached images skip the load event: If the browser serves the image from cache before your listener attaches, the load event never fires for that listener. Check img.complete first and read the value synchronously when it is true.
• Broken images report 0: A 404 or a CORS-blocked image leaves naturalWidth at 0 in every browser. Listen for the error event in parallel with load, and treat 0-valued naturalWidth as "no image" rather than "tiny image."
• currentSrc versus src on srcset: When the browser picks a different srcset candidate, naturalWidth reflects the chosen source, not the src attribute. Read img.currentSrc to know which file the browser actually decoded.
• Density mismatch on retina: A 1600 by 1600 raster served as a 2x asset reports 800 in naturalWidth, not 1600. Authors who debug an image-pipeline regression often blame the file on disk; the browser is correctly density-correcting the value.

In my experience, the trap that bites teams hardest is the cached-image case in single-page apps: a tab restore or a soft route change runs the layout code before the listener attaches, and naturalWidth is already populated but the load event never re-fires, so the dependent layout never recalculates.

Citations

All naturalWidth and naturalHeight version numbers and platform notes in this guide come from these primary sources:

• MDN Web Docs - HTMLImageElement.naturalWidth: developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/naturalWidth
• MDN Web Docs - HTMLImageElement.naturalHeight: developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/naturalHeight
• MDN Web Docs - HTMLImageElement.complete: developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/complete
• WHATWG HTML Standard - The img element: html.spec.whatwg.org/multipage/embedded-content.html#the-img-element
• WHATWG HTML Issue 3510 - Dimensionless images: github.com/whatwg/html/issues/3510
• Chrome Platform Status - HTMLImageElement: chromestatus.com/features#HTMLImageElement
• WebKit Bugzilla - naturalWidth implementation: bugs.webkit.org/show_bug.cgi?id=13037
• Mozilla Firefox release notes: mozilla.org/en-US/firefox/2.0/releasenotes
• Microsoft Learn - Internet Explorer DOM reference: learn.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer
• Wikipedia - HTML element: en.wikipedia.org/wiki/HTML_element
• Web Platform Baseline: web.dev/baseline