The HTMLImageElement
interface represents an HTML <img>
element, providing the properties and methods used to manipulate image elements.
The HTMLImageElement
interface represents an HTML <img>
element, providing the properties and methods used to manipulate image elements.
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')
.
Inherits properties from its parent, HTMLElement
.
HTMLImageElement.alt
A string 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 value 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 string 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 string 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 string 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.fetchPriority
Experimental
An optional string representing a hint given to the browser on how it should prioritize fetching of the image relative to other images. If this value is provided, it must be one of the possible permitted values: high
to fetch at a high priority, low
to fetch at a low priority, or auto
to indicate no preference (which is the default).
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 value 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 string 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 string 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 string 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 string 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 string 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 string 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.
HTMLImageElement.align
Deprecated
A string 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
Deprecated
A string which defines the width of the border surrounding the image. This is deprecated; use the CSS border
property instead.
HTMLImageElement.hspace
Deprecated
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
Deprecated
A string 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 place an <img>
inside an <a>
element defining the hyperlink.
HTMLImageElement.name
Deprecated
A string representing the name of the element.
HTMLImageElement.vspace
Deprecated
An integer value specifying the amount of empty space, in pixels, to leave above and below the image.
Inherits methods 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.
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:
src
attribute is empty or null
.src
URL is the same as the URL of the page the user is currently on.<img>
element's attributes.js
const img1 = new Image(); // Image constructor img1.src = "image1.png"; img1.alt = "alt"; document.body.appendChild(img1); const 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);
Specification |
---|
HTML Standard # htmlimageelement |
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | WebView Android | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | |
Image |
1 | 12 | 1 | 5.5 | 8 | 1 | 4.4 | 18 | 4 | 10.1 | 1 | 1.0 |
HTMLImageElement |
1 | 12 | 1 | 5.5 | 8 | 1 | 4.4 | 18 | 4 | 10.1 | 1 | 1.0 |
align |
1 | 12 | 1 | 5.5 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
alt |
1 | 12 | 1 | 5.5 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
attributionSrc |
117 | 117 | No | No | 103 | No | 117 | 117 | No | No | No | No |
border |
1 | 12 | 1 | 5.5 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
complete |
1 | 12 | 1 | 5.5IE reportsfalse for broken images. |
≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
crossOrigin |
13 | 12 | 8 | 11 | ≤12.1 | 6 | 4.4 | 18 | 8 | ≤12.1 | 6 | 1.0 |
currentSrc |
38 | 13 | 38 | No | 25 | 9.1 | 38 | 38 | 38 | 25 | 9.3 | 3.0 |
decode |
64 | 79 | 68 | No | 51 | 11.1 | 64 | 64 | 68 | 47 | 11.3 | 9.0 |
decoding |
65 | 79 | 63 | No | 52 | 11.1 | 65 | 65 | 63 | 47 | 11.3 | 9.0 |
fetchPriority |
102101–102 | 102101–102 | No | No | 8887–88 | preview | 102101–102 | 102101–102 | No | 70 | No | 19.0 |
height |
1 | 12 | 1 | 5.5 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
hspace |
1 | 12 | 1 | 5.5 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
isMap |
1 | 12 | 1 | 5.5 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
loading |
77 | 79 | 75 | No | 64 | 15.4 | 77 | 77 | 79 | 55 | 15.4 | 12.0 |
longDesc |
1 | 12 | 1 | 6 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
lowsrc |
1 | 12 | 1 | 6 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 2 | 1.0 |
name |
1 | 12 | 1 | 5.5 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
naturalHeight |
1 | 12 | 1 | 9 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
naturalWidth |
1 | 12 | 1 | 9 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
referrerPolicy |
5251–52 | 79 | 50 | No | 3938–39 | 14 | 5251–52 | 5251–52 | 50 | 41 | 14 | 6.05.0–6.0 |
sizes |
38 | 13 | 38 | No | 25 | 9.1 | 38 | 38 | 38 | 25 | 9.3 | 3.0 |
src |
1 | 12 | 1 | 5.5 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
srcset |
34 | 12 | 38 | No | 21 | 8 | 37 | 34 | 38 | 21 | 8 | 2.0 |
useMap |
1 | 12 | 1 | 5.5 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
vspace |
1 | 12 | 1 | 5.5 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
width |
1 | 12 | 1 | 5.5 | ≤12.1 | 3 | 4.4 | 18 | 4 | ≤12.1 | 1 | 1.0 |
x |
1 | 12 | 141–7 | No | ≤12.1 | 3 | 4.4 | 18 | 144–7 | ≤12.1 | 1 | 1.0 |
y |
1 | 12 | 141–7 | No | ≤12.1 | 3 | 4.4 | 18 | 144–7 | ≤12.1 | 1 | 1.0 |
<img>
© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement