{{APIRef("HTML DOM")}}
The HTMLImageElement
interface provides special properties and methods for manipulating the layout and presentation of {{HTMLElement("img")}} elements.
Properties
Inherits properties from its parent, {{domxref("HTMLElement")}}.
- {{domxref("HTMLImageElement.align")}} {{obsolete_inline}}
- Is a {{domxref("DOMString")}} indicating the alignment of the image with respect to the surrounding context.
- {{domxref("HTMLImageElement.alt")}}
- Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("alt", "img")}} HTML attribute, thus indicating fallback context for the image.
- {{domxref("HTMLImageElement.border")}} {{obsolete_inline}}
- Is a {{domxref("DOMString")}} that is responsible for the width of the border surrounding the image. This is now deprecated and the CSS {{cssxref("border")}} property should be used instead.
- {{domxref("HTMLImageElement.complete")}} {{readonlyInline}}
- Returns a {{domxref("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 {{domxref("HTMLImageElement.src", "src")}} value. - {{domxref("HTMLImageElement.crossOrigin")}}
- Is a {{domxref("DOMString")}} representing the CORS setting for this image element. See CORS settings attributes for further details.
- {{domxref("HTMLImageElement.currentSrc")}} {{readonlyInline}}{{experimental_inline}}
- Returns a {{domxref("DOMString")}}
- {{domxref("HTMLImageElement.height")}}
- Reflects the {{htmlattrxref("height", "img")}} HTML attribute, indicating the rendered height of the image in CSS pixels.
- {{domxref("HTMLImageElement.hspace")}} {{obsolete_inline}}
- Is a
long
representing the space on either side of the image. - {{domxref("HTMLImageElement.isMap")}}
- Is a {{domxref("Boolean")}} that reflects the {{htmlattrxref("ismap", "img")}} HTML attribute, indicating that the image is part of a server-side image map.
- {{domxref("HTMLImageElement.longDesc")}} {{obsolete_inline}}
- Is a {{domxref("DOMString")}} representing the URI of a long description of the image.
- {{domxref("HTMLImageElement.lowSrc")}} {{obsolete_inline}}
- Is a {{domxref("DOMString")}} hat refers to a low-quality (but faster to load) copy of the image.
- {{domxref("HTMLImageElement.name")}} {{obsolete_inline}}
- Is a {{domxref("DOMString")}}.
- {{domxref("HTMLImageElement.naturalHeight")}} {{readonlyInline}}
- Returns an
unsigned long
representing the intrinsic height of the image in CSS pixels, if it is available; else, it shows0
. - {{domxref("HTMLImageElement.naturalWidth")}} {{readonlyInline}}
- Returns an
unsigned long
representing the intrinsic width of the image in CSS pixels, if it is available; otherwise, it will show0
. - {{domxref("HTMLImageElement.referrerPolicy")}} {{experimental_inline}}
- Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("referrerpolicy", "img")}} HTML attribute indicating which referrer to use in order to fetch the image.
- {{domxref("HTMLImageElement.src")}}
- Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("src", "img")}} HTML attribute, containing the full URL of the image including base URI.
- {{domxref("HTMLImageElement.sizes")}} {{experimental_inline}}
- Is a {{domxref("DOMString")}}
- {{domxref("HTMLImageElement.srcset")}} {{experimental_inline}}
- Is a {{domxref("DOMString")}} reflecting the {{htmlattrxref("srcset", "img")}} 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. - {{domxref("HTMLImageElement.useMap")}}
- Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("usemap", "img")}} HTML attribute, containing a partial URL of a map element.
- {{domxref("HTMLImageElement.vspace")}} {{obsolete_inline}}
- Is a
long
representing the space above and below the image. - {{domxref("HTMLImageElement.width")}}
- Is an
unsigned long
that reflects the {{htmlattrxref("width", "img")}} HTML attribute, indicating the rendered width of the image in CSS pixels. - {{domxref("HTMLImageElement.x")}} {{readonlyInline}}{{experimental_inline}}
- Returns a
long
representing the horizontal offset from the nearest layer. This property mimics an old Netscape 4 behavior. - {{domxref("HTMLImageElement.y")}} {{readonlyInline}} {{experimental_inline}}
- 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, {{domxref("HTMLElement")}}.
- {{domxref("HTMLImageElement.Image()", "Image()")}}
- The
Image()
constructor, taking two optionalunsigned
long
, which are the width and the height of the resource, creates an instance ofHTMLImageElement
, 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 |
---|---|---|
{{SpecName('Referrer Policy', '#referrer-policy-delivery-referrer-attribute', 'referrer attribute')}} | {{Spec2('Referrer Policy')}} | Added the referrerPolicy property. |
{{SpecName("CSSOM View", "#excensions-to-the-htmlimageelement-interface", "Extensions to HTMLImageElement")}} | {{Spec2('CSSOM View')}} | Added the x and y properties. |
{{SpecName('HTML WHATWG', "embedded-content.html#the-img-element", "HTMLImageElement")}} | {{Spec2('HTML WHATWG')}} | The following properties have been added: srcset , currentSrc and sizes . |
{{SpecName('HTML5 W3C', "embedded-content-0.html#the-img-element", "HTMLImageElement")}} | {{Spec2('HTML5 W3C')}} | 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 . |
{{SpecName('DOM2 HTML', 'html.html#ID-17701901', 'HTMLImgElement')}} | {{Spec2('DOM2 HTML')}} | The lowSrc property has been removed.The following properties are now long , instead of DOMString : height , width , hspace , and vspace . |
{{SpecName('DOM1', 'level-one-html.html#ID-17701901', 'HTMLImgElement')}} | {{Spec2('DOM1')}} | Initial definition. |
Browser compatibility
{{CompatibilityTable}}
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|
Basic support | {{CompatVersionUnknown}} | {{CompatGeckoDesktop(1.0)}} | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} |
lowSrc |
{{CompatVersionUnknown}} | {{CompatVersionUnknown}} | {{CompatUnknown}} | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} |
naturalWidth , naturalHeight |
{{CompatVersionUnknown}} | {{CompatVersionUnknown}} | 9 | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} |
crossorigin |
{{CompatVersionUnknown}} | {{CompatVersionUnknown}} | {{CompatUnknown}} | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} |
complete |
{{CompatVersionUnknown}} | {{CompatVersionUnknown}} | 5[4] | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} |
srcset {{experimental_inline}} |
{{CompatChrome(34)}} | {{CompatGeckoDesktop(32)}}[2] | {{CompatNo}} | 21 | {{CompatSafari(7.1)}} |
currentSrc {{experimental_inline}} |
{{CompatVersionUnknown}} | {{CompatGeckoDesktop(32)}}[2] | {{CompatNo}} | {{CompatVersionUnknown}} | {{CompatNo}} |
sizes {{experimental_inline}} |
{{CompatVersionUnknown}} | {{CompatGeckoDesktop(33)}}[3] | {{CompatNo}} | {{CompatVersionUnknown}} | {{CompatNo}} |
x and y |
{{CompatVersionUnknown}} | 14[1] | {{CompatNo}} | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} |
referrerPolicy {{experimental_inline}} |
{{CompatNo}} | {{CompatGeckoDesktop(42)}} [5] | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
Feature | Android | Firefox Mobile (Gecko) | IE Phone | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|
Basic support | {{CompatVersionUnknown}} | {{CompatGeckoMobile(1.0)}} | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} |
lowSrc |
{{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} |
naturalWidth , naturalHeight |
{{CompatUnknown}} | {{CompatUnknown}} | 9 | {{CompatUnknown}} | {{CompatVersionUnknown}} |
crossorigin |
{{CompatUnknown}} | {{CompatVersionUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatVersionUnknown}} |
complete |
{{CompatUnknown}} | {{CompatVersionUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatVersionUnknown}} |
srcset {{experimental_inline}} |
{{CompatNo}} | {{CompatGeckoMobile(32)}}[2] | {{CompatNo}} | {{CompatNo}} | iOS 8 |
currentSrc {{experimental_inline}} |
{{CompatNo}} | {{CompatGeckoMobile(32)}}[2] | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
sizes {{experimental_inline}} |
{{CompatNo}} | {{CompatGeckoMobile(33)}}[3] | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
x and y |
{{CompatVersionUnknown}} | 14[1] | {{CompatNo}} | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} |
referrerPolicy {{experimental_inline}} |
{{CompatNo}} | {{CompatGeckoMobile(42)}} [5] | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
[1] Though, these x
and y
properties were removed in Gecko 7.0 {{geckoRelease("7.0")}} but later, they were restored in Gecko 14.0 {{geckoRelease("14.0")}} 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.
[5] This property was named referrer
from Firefox 42 to 44.
See also
- The HTML element implementing this interface: {{HTMLElement("img")}}