The HTMLImageElement interface provides special properties and methods  for manipulating the layout and presentation of <img> elements.

Properties

Inherits properties from its parent, HTMLElement.

HTMLImageElement.align
Is a DOMString indicating the alignment of the image with respect to the surrounding context.
HTMLImageElement.alt
Is a DOMString that reflects the alt HTML attribute,  thus indicating fallback context for the image.
HTMLImageElement.border
Is a DOMString that is responsible for the width of the border surrounding the image. This is now deprecated and the CSS border property should be used instead.
HTMLImageElement.complete Read only
Returns a Boolean that is true if the browser has finished fetching the image, whether successful or not. It also shows true, if the image has no src value.
HTMLImageElement.crossOrigin
Is a DOMString representing the CORS setting for this image element. See CORS settings attributes for further details.
HTMLImageElement.currentSrc Read only
Returns a DOMString representing the URL to the currently displayed image (which may change, for example in response to media queries).
HTMLImageElement.height
Is a unsigned long that reflects the height HTML attribute, indicating the rendered height of the image in CSS pixels.
HTMLImageElement.hspace
Is a long representing the space on either side of the image.
HTMLImageElement.isMap
Is a Boolean that reflects the ismap HTML attribute, indicating that the image is part of a server-side image map.
HTMLImageElement.longDesc
Is a DOMString representing the URI of a long description of the image.
HTMLImageElement.lowSrc
Is a DOMString that refers to a low-quality (but faster to load) copy of the image.
HTMLImageElement.name
Is a DOMString representing the name of the element.
HTMLImageElement.naturalHeight Read only
Returns a unsigned long representing the intrinsic height of the image in CSS pixels, if it is available; else, it shows 0.
HTMLImageElement.naturalWidth Read only
Returns a unsigned long representing the intrinsic width of the image in CSS pixels, if it is available; otherwise, it will show 0.
HTMLImageElement.referrerPolicy
Is a DOMString that reflects the referrerpolicy HTML attribute indicating which referrer to use in order to fetch the image.
HTMLImageElement.src
Is a DOMString that reflects the src HTML attribute, containing the full URL of the image including base URI.
HTMLImageElement.sizes
Is a DOMString reflecting the sizes HTML attribute.
HTMLImageElement.srcset
Is a DOMString reflecting the srcset HTML attribute, containing a list of candidate images, separated by a comma (',', U+002C COMMA). A candidate image is a URL followed by a 'w' with the width of the images, or an 'x' followed by the pixel density.
HTMLImageElement.useMap
Is a DOMString that reflects the usemap HTML attribute, containing a partial URL of a map element.
HTMLImageElement.vspace
Is a long representing the space above and below the image.
HTMLImageElement.width
Is a unsigned long that reflects the width HTML attribute, indicating the rendered width of the image in CSS pixels.
HTMLImageElement.x Read only
Returns a long representing the horizontal offset from the nearest layer. This property mimics an old Netscape 4 behavior.
HTMLImageElement.y Read only
Returns a long representing the vertical offset from the nearest layer. This property is also similar to behavior of an old Netscape 4.

Methods

Inherits properties from its parent, HTMLElement.

Image()
The Image() constructor, taking two optional unsigned long, which are the width and the height of the resource, creates an instance of HTMLImageElement , not inserted in a DOM tree.

Example

var img1 = new Image(); // HTML5 Constructor
img1.src = 'image1.png';
img1.alt = 'alt';
document.body.appendChild(img1);

var img2 = document.createElement('img'); // use DOM HTMLImageElement
img2.src = 'image2.jpg';
img2.alt = 'alt text';
document.body.appendChild(img2);

// using first image in the document
alert(document.images[0].src);

Specifications

Specification Status Comment
Referrer Policy
The definition of 'referrer attribute' in that specification.
Working Draft Added the referrerPolicy property.
CSS Object Model (CSSOM) View Module
The definition of 'Extensions to HTMLImageElement' in that specification.
Working Draft Added the x and y properties.
WHATWG HTML Living Standard
The definition of 'HTMLImageElement' in that specification.
Living Standard The following properties have been added: srcset, currentSrc and sizes.
HTML5
The definition of 'HTMLImageElement' in that specification.
Recommendation A constructor (with 2 optional parameters) has been added.
The following properties are now obsolete: name, border, align, hspace, vspace, and longdesc.
The following properties are now unsigned long, instead of long: height, and width.
The following properties have been added: crossorigin, naturalWidth, naturalHeight, and complete.
Document Object Model (DOM) Level 2 HTML Specification
The definition of 'HTMLImgElement' in that specification.
Recommendation The lowSrc property has been removed.
The following properties are now long, instead of DOMString: height, width, hspace, and vspace.
Document Object Model (DOM) Level 1 Specification
The definition of 'HTMLImgElement' in that specification.
Recommendation Initial definition.

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support (Yes) 1.0 (1.7 or earlier) (Yes) (Yes) (Yes)
lowSrc (Yes) (Yes) ? (Yes) (Yes)
naturalWidth, naturalHeight (Yes) (Yes) 9 (Yes) (Yes)
crossorigin (Yes) (Yes) 9 (Yes) (Yes)
complete (Yes) (Yes) 5[4] (Yes) (Yes)
srcset 34 32 (32)[2] No support 21 7.1
currentSrc (Yes) 32 (32)[2] No support (Yes) No support
sizes (Yes) 33 (33)[3] No support (Yes) No support
x and y (Yes) 14[1] No support (Yes) (Yes)
referrerPolicy No support 50 (50) No support No support No support
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support (Yes) 1.0 (1.0) (Yes) (Yes) (Yes)
lowSrc ? ? ? ? ?
naturalWidth, naturalHeight ? ? 9 ? (Yes)
crossorigin ? (Yes) ? ? (Yes)
complete ? (Yes) ? ? (Yes)
srcset No support 32.0 (32)[2] No support No support iOS 8
currentSrc No support 32.0 (32)[2] No support No support No support
sizes No support 33.0 (33)[3] No support No support No support
x and y (Yes) 14[1] No support (Yes) (Yes)
referrerPolicy No support 50.0 (50) No support No support No support

[1] Though, these x and y properties were removed in Gecko 7.0 (Firefox 7.0 / Thunderbird 7.0 / SeaMonkey 2.4) but later, they were restored in Gecko 14.0 (Firefox 14.0 / Thunderbird 14.0 / SeaMonkey 2.11) for compatibility reasons.

[2] This feature is behind the dom.image.srcset.enabled preference, defaulting to false.

[3] This feature is behind the dom.image.picture.enabled preference, defaulting to false.

[4] IE reports false for broken images.

See also

  • The HTML element implementing this interface: <img>