Web/API/HTMLImageElement

From Get docs


The HTMLImageElement interface represents an HTML <img> element, providing the properties and methods used to manipulate image elements.

Constructor

Image()
The Image() constructor creates and returns a new HTMLImageElement object representing an HTML <img> element which is not attached to any DOM tree. It accepts optional width and height parameters. When called without parameters, new Image() is equivalent to calling document.createElement("img").

Properties

Inherits properties from its parent, HTMLElement.

HTMLImageElement.alt
A DOMString that reflects the alt HTML attribute, thus indicating the alternate fallback content to be displayed if the image has not been loaded.
HTMLImageElement.complete Read only
Returns a Boolean that is true if the browser has finished fetching the image, whether successful or not. That means this value is also true if the image has no src value indicating an image to load.
HTMLImageElement.crossOrigin
A DOMString specifying the CORS setting for this image element. See CORS settings attributes for further details. This may be null if CORS is not used.
HTMLImageElement.currentSrc Read only
Returns a USVString representing the URL from which the currently displayed image was loaded. This may change as the image is adjusted due to changing conditions, as directed by any media queries which are in place.
HTMLImageElement.decoding
An optional DOMString representing a hint given to the browser on how it should decode the image. If this value is provided, it must be one of the possible permitted values: sync to decode the image synchronously, async to decode it asynchronously, or auto to indicate no preference (which is the default). Read the decoding page for details on the implications of this property's values.
HTMLImageElement.height
An integer value that reflects the height HTML attribute, indicating the rendered height of the image in CSS pixels.
HTMLImageElement.isMap
A Boolean that reflects the ismap HTML attribute, indicating that the image is part of a server-side image map. This is different from a client-side image map, specified using an <img> element and a corresponding <map> which contains <area> elements indicating the clickable areas in the image. The image must be contained within an <a> element; see the ismap page for details.
HTMLImageElement.loading
A DOMString providing a hint to the browser used to optimize loading the document by determining whether to load the image immediately (eager) or on an as-needed basis (lazy).
HTMLImageElement.naturalHeight Read only
Returns an integer value representing the intrinsic height of the image in CSS pixels, if it is available; else, it shows 0. This is the height the image would be if it were rendered at its natural full size.
HTMLImageElement.naturalWidth Read only
An integer value representing the intrinsic width of the image in CSS pixels, if it is available; otherwise, it will show 0. This is the width the image would be if it were rendered at its natural full size.
HTMLImageElement.referrerPolicy
A DOMString that reflects the referrerpolicy HTML attribute, which tells the user agent how to decide which referrer to use in order to fetch the image. Read this article for details on the possible values of this string.
HTMLImageElement.sizes
A DOMString reflecting the sizes HTML attribute. This string specifies a list of comma-separated conditional sizes for the image; that is, for a given viewport size, a particular image size is to be used. Read the documentation on the sizes page for details on the format of this string.
HTMLImageElement.src
A USVString that reflects the src HTML attribute, which contains the full URL of the image including base URI. You can load a different image into the element by changing the URL in the src attribute.
HTMLImageElement.srcset
A USVString reflecting the srcset HTML attribute. This specifies a list of candidate images, separated by commas (',', U+002C COMMA). Each candidate image is a URL followed by a space, followed by a specially-formatted string indicating the size of the image. The size may be specified either the width or a size multiple. Read the srcset page for specifics on the format of the size substring.
HTMLImageElement.useMap
A DOMString reflecting the usemap HTML attribute, containing the page-local URL of the <map> element describing the image map to use. The page-local URL is a pound (hash) symbol (#) followed by the ID of the <map> element, such as #my-map-element. The <map> in turn contains <area> elements indicating the clickable areas in the image.
HTMLImageElement.width
An integer value that reflects the width HTML attribute, indicating the rendered width of the image in CSS pixels.
HTMLImageElement.x Read only
An integer indicating the horizontal offset of the left border edge of the image's CSS layout box relative to the origin of the <html> element's containing block.
HTMLImageElement.y Read only
The integer vertical offset of the top border edge of the image's CSS layout box relative to the origin of the <html> element's containing block.

Obsolete properties

HTMLImageElement.align '
A DOMString indicating the alignment of the image with respect to the surrounding context. The possible values are "left", "right", "justify", and "center". This is obsolete; you should instead use CSS (such as text-align, which works with images despite its name) to specify the alignment.
HTMLImageElement.border '
A DOMString which defines the width of the border surrounding the image. This is deprecated; use the CSS border property instead.
HTMLImageElement.hspace '
An integer value which specifies the amount of space (in pixels) to leave empty on the left and right sides of the image.
HTMLImageElement.longDesc '
A USVString specifying the URL at which a long description of the image's contents may be found. This is used to turn the image into a hyperlink automatically. Modern HTML should instead simply place an <img> inside an <a> element defining the hyperlink.
HTMLImageElement.lowsrc '
A USVString specifying the URL of a low-quality (but faster to load) version of the same image. This was once used by browsers under constrained network conditions or on slow devices.
HTMLImageElement.name '
A DOMString representing the name of the element.
HTMLImageElement.vspace '
An integer value specifying the amount of empty space, in pixels, to leave above and below the image.

Methods

Inherits properties from its parent, HTMLElement.

HTMLImageElement.decode()
Returns a Promise that resolves when the image is decoded and it's safe to append the image to the DOM. This prevents rendering of the next frame from having to pause to decode the image, as would happen if an undecoded image were added to the DOM.

Errors

If an error occurs while trying to load or render the image, and an onerror event handler has been configured to handle the error event, that event handler will get called. This can happen in a number of situations, including:

  • The src attribute is empty or null.
  • The specified src URL is the same as the URL of the page the user is currently on.
  • The specified image is corrupted in some way that prevents it from being loaded.
  • The specified image's metadata is corrupted in such a way that it's impossible to retrieve its dimensions, and no dimensions were specified in the <img> element's attributes.
  • The specified image is in a format not supported by the user agent.

Example

var img1 = new Image(); // Image 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
CSS Object Model (CSSOM) View ModuleThe definition of 'Extensions to HTMLImageElement' in that specification. Working Draft Added the x and y properties.
HTML Living StandardThe definition of 'HTMLImageElement' in that specification. Living Standard The following properties have been added: srcset, currentSrc and sizes.
HTML5The 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 SpecificationThe definition of 'HTMLImgElement' in that specification. Obsolete 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 SpecificationThe definition of 'HTMLImgElement' in that specification. Obsolete Initial definition.

Browser compatibility

Update compatibility data on GitHub

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari Android webview Chrome for Android Firefox for Android Opera for Android Safari on iOS Samsung Internet
HTMLImageElement Chrome

Full support 1

Edge

Full support 12

Firefox

Full support 1

IE

Full support 5.5

Opera

Full support 8

Safari

Full support 3

WebView Android

Full support 1

Chrome Android

Full support 18

Firefox Android

Full support 4

Opera Android

Full support 10.1

Safari iOS

Full support 1

Samsung Internet Android

Full support 1.0

Image() constructor Chrome

Full support 1

Edge

Full support 12

Firefox

Full support 1

IE

Full support 8

Opera

Full support 8

Safari

Full support 10.1

WebView Android

Full support 1

Chrome Android

Full support 18

Firefox Android

Full support 4

Opera Android

?

Safari iOS

Full support 1

Samsung Internet Android

Full support 1.0

align

Deprecated'

Chrome

Full support 1

Edge

Full support 12

Firefox

Full support 1

IE

Full support 5.5

Opera

Full support ≤12.1

Safari

Full support 3

WebView Android

Full support Yes

Chrome Android

Full support Yes

Firefox Android

Full support 4

Opera Android

Full support ≤12.1

Safari iOS

Full support 1

Samsung Internet Android

Full support Yes

alt Chrome

Full support 1

Edge

Full support 12

Firefox

Full support 1

IE

Full support 5.5

Opera

Full support ≤12.1

Safari

Full support 3

WebView Android

Full support Yes

Chrome Android

Full support Yes

Firefox Android

Full support 4

Opera Android

Full support ≤12.1

Safari iOS

Full support 1

Samsung Internet Android

Full support Yes

border

Deprecated'

Chrome

Full support 1

Edge

Full support 12

Firefox

Full support 1

IE

Full support 5.5

Opera

Full support ≤12.1

Safari

Full support 3

WebView Android

Full support Yes

Chrome Android

Full support Yes

Firefox Android

Full support 4

Opera Android

Full support ≤12.1

Safari iOS

Full support 1

Samsung Internet Android

Full support Yes

complete Chrome

Full support 1

Edge

Full support 12

Firefox

Full support 1

IE Full support 5.5

Notes'

Full support 5.5

Notes'

Notes' IE reports false for broken images.

Opera

Full support ≤12.1

Safari

Full support 3

WebView Android

Full support Yes

Chrome Android

Full support Yes

Firefox Android

Full support 4

Opera Android

Full support ≤12.1

Safari iOS

Full support 1

Samsung Internet Android

Full support Yes

crossOrigin Chrome

Full support 13

Edge

Full support 12

Firefox

Full support 8

IE

Full support 11

Opera

Full support ≤12.1

Safari

Full support 6

WebView Android

Full support Yes

Chrome Android

Full support Yes

Firefox Android

Full support 8

Opera Android

Full support ≤12.1

Safari iOS

Full support 6

Samsung Internet Android

Full support Yes

currentSrc

Experimental'

Chrome

Full support 38

Edge

Full support 13

Firefox Full support 38


Full support 38


No support 32 — 52

Disabled'

Disabled' From version 32 until version 52 (exclusive): this feature is behind the dom.image.srcset.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.

IE

No support No

Opera

Full support 25

Safari

Full support 9

WebView Android

Full support 38

Chrome Android

Full support 38

Firefox Android Full support 38


Full support 38


No support 32 — 52

Disabled'

Disabled' From version 32 until version 52 (exclusive): this feature is behind the dom.image.srcset.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.

Opera Android

Full support 25

Safari iOS

Full support 9

Samsung Internet Android

Full support 3.0

decode() Chrome

Full support 64

Edge

Full support 79

Firefox

Full support 68

IE

No support No

Opera

Full support 51

Safari

Full support 11.1

WebView Android

Full support 64

Chrome Android

Full support 64

Firefox Android

Full support 68

Opera Android

Full support 47

Safari iOS

Full support 11.3

Samsung Internet Android

Full support 9.0

decoding Chrome

Full support 65

Edge

Full support 79

Firefox

Full support 63

IE

No support No

Opera

Full support 52

Safari

Full support 11.1

WebView Android

Full support 65

Chrome Android

Full support 65

Firefox Android

Full support 63

Opera Android

Full support 47

Safari iOS

Full support 11.3

Samsung Internet Android

Full support 9.0

error event Chrome

No support No

Edge

No support No

Firefox Full support 51

Notes'

Full support 51

Notes'

Notes' May also be supported in earlier versions.

IE

No support No

Opera

Full support Yes

Safari

Full support Yes

WebView Android

No support No

Chrome Android

No support No

Firefox Android

Full support 51

Opera Android

Full support Yes

Safari iOS

Full support Yes

Samsung Internet Android

No support No

height Chrome

Full support 1

Edge

Full support 12

Firefox

Full support 1

IE

Full support 5.5

Opera

Full support ≤12.1

Safari

Full support 3

WebView Android

Full support Yes

Chrome Android

Full support Yes

Firefox Android

Full support 4

Opera Android

Full support ≤12.1

Safari iOS

Full support 1

Samsung Internet Android

Full support Yes

hspace

Deprecated'

Chrome

Full support 1

Edge

Full support 12

Firefox

Full support 1

IE

Full support 5.5

Opera

Full support ≤12.1

Safari

Full support 3

WebView Android

Full support Yes

Chrome Android

Full support Yes

Firefox Android

Full support 4

Opera Android

Full support ≤12.1

Safari iOS

Full support 1

Samsung Internet Android

Full support Yes

isMap Chrome

Full support 1

Edge

Full support 12

Firefox

Full support 1

IE

Full support 5.5

Opera

Full support ≤12.1

Safari

Full support 3

WebView Android

Full support Yes

Chrome Android

Full support Yes

Firefox Android

Full support 4

Opera Android

Full support ≤12.1

Safari iOS

Full support 1

Samsung Internet Android

Full support Yes

loading

Experimental'

Chrome

Full support 77

Edge

Full support 79

Firefox

Full support 75

IE

No support No

Opera

Full support 64

Safari No support No

Notes'

No support No

Notes'

Notes' See bug 196698

WebView Android

No support No

Chrome Android

Full support 77

Firefox Android

No support No

Opera Android

Full support 55

Safari iOS No support No

Notes'

No support No

Notes'

Notes' See bug 196698

Samsung Internet Android

Full support 12.0

longDesc

Deprecated'

Chrome

Full support 1

Edge

Full support 12

Firefox

Full support 1

IE

Full support 6

Opera

Full support ≤12.1

Safari

Full support 3

WebView Android

Full support Yes

Chrome Android

Full support Yes

Firefox Android

Full support 4

Opera Android

Full support ≤12.1

Safari iOS

Full support 1

Samsung Internet Android

Full support Yes

lowSrc

Deprecated'

Chrome

Full support 1

Edge

Full support ≤18

Firefox

Full support Yes

IE

?

Opera

Full support Yes

Safari

Full support Yes

WebView Android

Full support Yes

Chrome Android

Full support Yes

Firefox Android

?

Opera Android

?

Safari iOS

?

Samsung Internet Android

Full support Yes

name

Deprecated'

Chrome

Full support 1

Edge

Full support 12

Firefox

Full support 1

IE

Full support 5.5

Opera

Full support ≤12.1

Safari

Full support 3

WebView Android

Full support Yes

Chrome Android

Full support Yes

Firefox Android

Full support 4

Opera Android

Full support ≤12.1

Safari iOS

Full support 1

Samsung Internet Android

Full support Yes

naturalHeight Chrome

Full support 1

Edge

Full support 12

Firefox

Full support 1

IE

Full support 9

Opera

Full support ≤12.1

Safari

Full support 3

WebView Android

Full support Yes

Chrome Android

Full support Yes

Firefox Android

Full support 4

Opera Android

Full support ≤12.1

Safari iOS

Full support 1

Samsung Internet Android

Full support Yes

naturalWidth Chrome

Full support 1

Edge

Full support 12

Firefox

Full support 1

IE

Full support 9

Opera

Full support ≤12.1

Safari

Full support 3

WebView Android

Full support Yes

Chrome Android

Full support Yes

Firefox Android

Full support 4

Opera Android

Full support ≤12.1

Safari iOS

Full support 1

Samsung Internet Android

Full support Yes

onerror Chrome

No support No

Edge

No support No

Firefox Full support 51

Notes'

Full support 51

Notes'

Notes' May also be supported in earlier versions.

IE

No support No

Opera

Full support Yes

Safari

Full support Yes

WebView Android

No support No

Chrome Android

No support No

Firefox Android

Full support 51

Opera Android

Full support Yes

Safari iOS

Full support Yes

Samsung Internet Android

No support No

referrerPolicy Chrome

Full support 53

Edge

Full support 79

Firefox

Full support 50

IE

No support No

Opera

Full support 40

Safari

Full support 14

WebView Android

Full support 53

Chrome Android

Full support 53

Firefox Android

Full support 50

Opera Android

Full support 41

Safari iOS

Full support 14

Samsung Internet Android

Full support 6.0

sizes

Experimental'

Chrome

Full support 38

Edge

Full support 13

Firefox Full support 38


Full support 38


No support 33 — 52

Disabled'

Disabled' From version 33 until version 52 (exclusive): this feature is behind the dom.image.picture.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.

IE

No support No

Opera

Full support 25

Safari

Full support 9

WebView Android

Full support 38

Chrome Android

Full support 38

Firefox Android Full support 38


Full support 38


No support 33 — 52

Disabled'

Disabled' From version 33 until version 52 (exclusive): this feature is behind the dom.image.picture.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.

Opera Android

Full support 25

Safari iOS

Full support 9

Samsung Internet Android

Full support 3.0

src Chrome

Full support 1

Edge

Full support 12

Firefox

Full support 1

IE

Full support 5.5

Opera

Full support ≤12.1

Safari

Full support 3

WebView Android

Full support Yes

Chrome Android

Full support Yes

Firefox Android

Full support 4

Opera Android

Full support ≤12.1

Safari iOS

Full support 1

Samsung Internet Android

Full support Yes

srcset

Experimental'

Chrome

Full support 34

Edge

Full support 12

Firefox Full support 38


Full support 38


No support 32 — 52

Disabled'

Disabled' From version 32 until version 52 (exclusive): this feature is behind the dom.image.srcset.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.

IE

No support No

Opera

Full support 21

Safari

Full support 6.1

WebView Android

Full support 37

Chrome Android

Full support 34

Firefox Android Full support 38


Full support 38


No support 32 — 52

Disabled'

Disabled' From version 32 until version 52 (exclusive): this feature is behind the dom.image.srcset.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.

Opera Android

No support No

Safari iOS

Full support 6.1

Samsung Internet Android

Full support 2.0

useMap

Deprecated'

Chrome

Full support 1

Edge

Full support 12

Firefox

Full support 1

IE

Full support 5.5

Opera

Full support ≤12.1

Safari

Full support 3

WebView Android

Full support Yes

Chrome Android

Full support Yes

Firefox Android

Full support 4

Opera Android

Full support ≤12.1

Safari iOS

Full support 1

Samsung Internet Android

Full support Yes

vspace

Deprecated'

Chrome

Full support 1

Edge

Full support 12

Firefox

Full support 1

IE

Full support 5.5

Opera

Full support ≤12.1

Safari

Full support 3

WebView Android

Full support Yes

Chrome Android

Full support Yes

Firefox Android

Full support 4

Opera Android

Full support ≤12.1

Safari iOS

Full support 1

Samsung Internet Android

Full support Yes

width Chrome

Full support 1

Edge

Full support 12

Firefox

Full support 1

IE

Full support 5.5

Opera

Full support ≤12.1

Safari

Full support 3

WebView Android

Full support Yes

Chrome Android

Full support Yes

Firefox Android

Full support 4

Opera Android

Full support ≤12.1

Safari iOS

Full support 1

Samsung Internet Android

Full support Yes

x Chrome

Full support 1

Edge

Full support 12

Firefox Full support 14


Full support 14


No support ? — 7


IE

No support No

Opera

Full support ≤12.1

Safari

Full support 3

WebView Android

Full support Yes

Chrome Android

Full support Yes

Firefox Android Full support 14


Full support 14


No support ? — 7


Opera Android

Full support ≤12.1

Safari iOS

Full support 1

Samsung Internet Android

Full support Yes

y Chrome

Full support 1

Edge

Full support 12

Firefox Full support 14


Full support 14


No support ? — 7


IE

No support No

Opera

Full support ≤12.1

Safari

Full support 3

WebView Android

Full support Yes

Chrome Android

Full support Yes

Firefox Android Full support 14


Full support 14


No support ? — 7


Opera Android

Full support ≤12.1

Safari iOS

Full support 1

Samsung Internet Android

Full support Yes

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
Experimental. Expect behavior to change in the future.'
Experimental. Expect behavior to change in the future.
Deprecated. Not for use in new websites.'
Deprecated. Not for use in new websites.
See implementation notes.'
See implementation notes.
User must explicitly enable this feature.'
User must explicitly enable this feature.


See also

  • The HTML element implementing this interface: <img>