The HTMLImageElement
interface represents an HTML <img>
element, providing the properties and methods used to manipulate image elements.
<div id="interfaceDiagram" style="display: inline-block; position: relative; width: 100%; padding-bottom: 20%; vertical-align: middle; overflow: hidden;"><svg style="display: inline-block; position: absolute; top: 0; left: 0;" viewbox="-50 0 600 120" preserveAspectRatio="xMinYMin meet"><a xlink:href="/docs/Web/API/EventTarget" target="_top"><rect x="1" y="1" width="110" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text x="56" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">EventTarget</text></a><polyline points="111,25 121,20 121,30 111,25" stroke="#D4DDE4" fill="none"/><line x1="121" y1="25" x2="151" y2="25" stroke="#D4DDE4"/><a xlink:href="/docs/Web/API/Node" target="_top"><rect x="151" y="1" width="75" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text x="188.5" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">Node</text></a><polyline points="226,25 236,20 236,30 226,25" stroke="#D4DDE4" fill="none"/><line x1="236" y1="25" x2="266" y2="25" stroke="#D4DDE4"/><a xlink:href="/docs/Web/API/Element" target="_top"><rect x="266" y="1" width="75" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text x="303.5" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">Element</text></a><polyline points="341,25 351,20 351,30 341,25" stroke="#D4DDE4" fill="none"/><line x1="351" y1="25" x2="381" y2="25" stroke="#D4DDE4"/><a xlink:href="/docs/Web/API/HTMLElement" target="_top"><rect x="381" y="1" width="110" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text x="436" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">HTMLElement</text></a><polyline points="491,25 501,20 501,30 491,25" stroke="#D4DDE4" fill="none"/><line x1="501" y1="25" x2="509" y2="25" stroke="#D4DDE4"/><line x1="509" y1="25" x2="509" y2="90" stroke="#D4DDE4"/><line x1="509" y1="90" x2="492" y2="90" stroke="#D4DDE4"/><a xlink:href="/docs/Web/API/HTMLImageElement" target="_top"><rect x="331" y="65" width="160" height="50" fill="#F4F7F8" stroke="#D4DDE4" stroke-width="2px" /><text x="411" y="94" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">HTMLImageElement</text></a></svg></div>
a:hover text { fill: #0095DD; pointer-events: all;}
Constructor
Image()
- The
Image()
constructor creates and returns a newHTMLImageElement
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 callingdocument.createElement("img")
.
Properties
Inherits properties from its parent, HTMLElement
.
HTMLImageElement.alt
- A
DOMString
that reflects thealt
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 istrue
if the browser has finished fetching the image, whether successful or not. That means this value is alsotrue
if the image has nosrc
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 benull
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, orauto
to indicate no preference (which is the default). Read thedecoding
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 theismap
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 theismap
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 thereferrerpolicy
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 thesizes
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 thesizes
page for details on the format of this string. HTMLImageElement.src
- A
USVString
that reflects thesrc
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 thesrc
attribute. HTMLImageElement.srcset
- A
USVString
reflecting thesrcset
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 thesrcset
page for specifics on the format of the size substring. HTMLImageElement.useMap
- A
DOMString
reflecting theusemap
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 astext-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 CSSborder
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 ornull
. - 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 Module The definition of 'Extensions to HTMLImageElement' in that specification. |
Working Draft | Added the x and y properties. |
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. |
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 Specification The definition of 'HTMLImgElement' in that specification. |
Obsolete | Initial definition. |
Browser compatibility
The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
HTMLImageElement | Chrome Full support 1 | Edge Full support 12 | Firefox Full support 1 | IE Full support 8 | 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 | Chrome Full support 1 | Edge Full support 12 | 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 Full support Yes | Opera Android ? | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
alt | Chrome Full support 1 | Edge Full support 12 | 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 Full support Yes | Opera Android ? | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
border | Chrome Full support 1 | Edge Full support 12 | 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 Full support Yes | Opera Android ? | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
complete | Chrome Full support 1 | Edge Full support 12 | Firefox Full support Yes | IE
Full support
8
| Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android ? | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
crossOrigin | Chrome Full support 13 | Edge Full support 12 | Firefox Full support Yes | IE Full support 9 | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android ? | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
currentSrc | Chrome Full support 45 | Edge Full support 13 | Firefox
Full support
38
| IE No support No | Opera Full support Yes | Safari Full support 10.1 | WebView Android Full support 45 | Chrome Android Full support 45 | Firefox Android
Full support
38
| Opera Android No support No | Safari iOS Full support 10.3 | Samsung Internet Android Full support 5.0 |
decode() | Chrome Full support 64 | Edge Full support ≤79 | Firefox Full support 68 | IE ? | Opera Full support Yes | Safari Full support 11.1 | WebView Android Full support 64 | Chrome Android Full support 64 | Firefox Android Full support 68 | Opera Android ? | 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 Yes | Safari Full support 11.1 | WebView Android Full support 65 | Chrome Android Full support 65 | Firefox Android Full support 63 | Opera Android ? | 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
| 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 Yes | IE ? | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android ? | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
hspace | Chrome Full support 1 | Edge Full support 12 | 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 Full support Yes | Opera Android ? | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
isMap | Chrome Full support 1 | Edge Full support 12 | 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 Full support Yes | Opera Android ? | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
loading | Chrome Full support 76 | Edge Full support 79 | Firefox Full support 75 | IE No support No | Opera Full support 63 | Safari
No support
No
| WebView Android No support No | Chrome Android Full support 76 | Firefox Android No support No | Opera Android Full support 54 | Safari iOS
No support
No
| Samsung Internet Android No support No |
longDesc | Chrome Full support 1 | Edge Full support 12 | 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 Full support Yes | Opera Android ? | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
lowSrc | 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 | Chrome Full support 1 | Edge Full support 12 | 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 Full support Yes | Opera Android ? | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
naturalHeight | Chrome Full support 1 | Edge Full support 12 | Firefox Full support Yes | IE Full support 9 | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android ? | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
naturalWidth | Chrome Full support 1 | Edge Full support 12 | Firefox Full support Yes | IE Full support 9 | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support Yes | Opera Android ? | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
onerror | Chrome No support No | Edge No support No | Firefox
Full support
51
| 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 51 | Edge Full support 79 | Firefox Full support 50 | IE No support No | Opera Full support 38 | Safari Full support 11.1 | WebView Android Full support 51 | Chrome Android Full support 51 | Firefox Android Full support 50 | Opera Android Full support 41 | Safari iOS No support No | Samsung Internet Android Full support 5.0 |
sizes | Chrome Full support 45 | Edge Full support 13 | Firefox
Full support
38
| IE No support No | Opera Full support Yes | Safari No support No | WebView Android Full support 45 | Chrome Android Full support 45 | Firefox Android
Full support
38
| Opera Android No support No | Safari iOS No support No | Samsung Internet Android Full support 5.0 |
src | Chrome Full support 1 | Edge Full support 12 | 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 Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
srcset | Chrome Full support 34 | Edge Full support 12 | Firefox
Full support
38
| IE No support No | Opera Full support 21 | Safari Full support 8 | WebView Android Full support 37 | Chrome Android Full support 34 | Firefox Android
Full support
38
| Opera Android No support No | Safari iOS Full support 8 | Samsung Internet Android Full support 2.0 |
useMap | Chrome Full support 1 | Edge Full support 12 | 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 Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
vspace | Chrome Full support 1 | Edge Full support 12 | 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 Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
width | Chrome Full support 1 | Edge Full support 12 | 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 Full support Yes | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
x | Chrome Full support 1 | Edge Full support 12 | Firefox
Full support
14
| IE No support No | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android
Full support
14
| Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
y | Chrome Full support 1 | Edge Full support 12 | Firefox
Full support
14
| IE No support No | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android
Full support
14
| Opera Android Full support Yes | Safari iOS Full support Yes | 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.
- 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>