HTML Living Standard — Last Updated

4.8 Embedded content

4.8.1 The picture element

✔ MDN Element/picture Support in all current engines. Firefox 38+ Safari 9.1+ Chrome 38+ Opera 25+ Edge 79+ Edge (Legacy) 13+ Internet Explorer No Firefox Android 38+ Safari iOS 9.3+ Chrome Android 38+ WebView Android 38+ Samsung Internet 3.0+ Opera Android 25+ caniuse.com table

✔ MDN HTMLPictureElement Support in all current engines. Firefox 38+ Safari 9.1+ Chrome 38+ Opera 25+ Edge 79+ Edge (Legacy) 13+ Internet Explorer No Firefox Android 38+ Safari iOS 9.3+ Chrome Android 38+ WebView Android 38+ Samsung Internet 3.0+ Opera Android 25+

The picture element is a container which provides multiple sources to its contained img element to allow authors to declaratively control or give hints to the user agent about which image resource to use, based on the screen pixel density, viewport size, image format, and other factors. It represents its children.

The picture element is somewhat different from the similar-looking video and audio elements. While all of them contain source elements, the source element's src attribute has no meaning when the element is nested within a picture element, and the resource selection algorithm is different. Also, the picture element itself does not display anything; it merely provides a context for its contained img element that enables it to choose from multiple URLs.

4.8.2 The source element

✔ MDN Element/source Support in all current engines. Firefox 3.5+ Safari Yes Chrome Yes Opera Yes Edge Yes Edge (Legacy) 12+ Internet Explorer 9+ Firefox Android 4+ Safari iOS Yes Chrome Android Yes WebView Android Yes Samsung Internet Yes Opera Android ?

✔ MDN HTMLSourceElement Support in all current engines. Firefox 3.5+ Safari Yes Chrome Yes Opera Yes Edge Yes Edge (Legacy) 12+ Internet Explorer 9+ Firefox Android 4+ Safari iOS Yes Chrome Android Yes WebView Android Yes Samsung Internet Yes Opera Android Yes

The source element allows authors to specify multiple alternative source sets for img elements or multiple alternative media resources for media elements. It does not represent anything on its own.

The type attribute may be present. If present, the value must be a valid MIME type string.

The remainder of the requirements depend on whether the parent is a picture element or a media element:

If a source element is inserted as a child of a media element that has no src attribute and whose networkState has the value NETWORK_EMPTY , the user agent must invoke the media element's resource selection algorithm.

The IDL attributes src , type , srcset , sizes and media must reflect the respective content attributes of the same name.

If the author isn't sure if user agents will all be able to render the media resources provided, the author can listen to the error event on the last source element and trigger fallback behavior: < script > function fallback ( video ) { // replace <video> with its contents while ( video . hasChildNodes ()) { if ( video . firstChild instanceof HTMLSourceElement ) video . removeChild ( video . firstChild ); else video . parentNode . insertBefore ( video . firstChild , video ); } video . parentNode . removeChild ( video ); } </ script > < video controls autoplay > < source src = 'video.mp4' type = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"' > < source src = 'video.ogv' type = 'video/ogg; codecs="theora, vorbis"' onerror = "fallback(parentNode)" > ... </ video >

4.8.3 The img element

✔ MDN Element/img Support in all current engines. Firefox Yes Safari Yes Chrome Yes Opera Yes Edge Yes Edge (Legacy) 12+ Internet Explorer Yes Firefox Android Yes Safari iOS Yes Chrome Android Yes WebView Android Yes Samsung Internet Yes Opera Android Yes

✔ MDN HTMLImageElement Support in all current engines. Firefox 1+ Safari 3+ Chrome 1+ Opera 8+ Edge 79+ Edge (Legacy) 12+ Internet Explorer 8+ Firefox Android 4+ Safari iOS 1+ Chrome Android 18+ WebView Android 1+ Samsung Internet 1.0+ Opera Android 10.1+

An img element represents an image.

✔ MDN Element/img#attr-srcset Support in all current engines. Firefox 38+ Safari 8+ Chrome 34+ Opera 21+ Edge 79+ Edge (Legacy) ≤18+ Internet Explorer No Firefox Android 38+ Safari iOS 8+ Chrome Android 34+ WebView Android 37+ Samsung Internet 2.0+ Opera Android 21+ caniuse.com table

The image given by the src and srcset attributes, and any previous sibling source elements' srcset attributes if the parent is a picture element, is the embedded content; the value of the alt attribute provides equivalent content for those who cannot process images or who have image loading disabled (i.e. it is the img element's fallback content).

The requirements on the alt attribute's value are described in a separate section.

The src attribute must be present, and must contain a valid non-empty URL potentially surrounded by spaces referencing a non-interactive, optionally animated, image resource that is neither paged nor scripted.

The requirements above imply that images can be static bitmaps (e.g. PNGs, GIFs, JPEGs), single-page vector documents (single-page PDFs, XML files with an SVG document element), animated bitmaps (APNGs, animated GIFs), animated vector graphics (XML files with an SVG document element that use declarative SMIL animation), and so forth. However, these definitions preclude SVG files with script, multipage PDF files, interactive MNG files, HTML documents, plain text documents, and so forth. [PNG] [GIF] [JPEG] [PDF] [XML] [APNG] [SVG] [MNG]

The srcset attribute may also be present, and is a srcset attribute.

The srcset attribute and the src attribute (if width descriptors are not used) contribute the image sources to the source set (if no source element was selected).

If the srcset attribute is present and has any using a width descriptor, the sizes attribute must also be present, and is a sizes attribute. The sizes attribute contributes the source size to the source set (if no source element was selected).

✔ MDN Attributes/crossorigin Support in all current engines. Firefox Yes Safari Yes Chrome Yes Opera Yes Edge Yes Edge (Legacy) 12+ Internet Explorer Yes Firefox Android Yes Safari iOS Yes Chrome Android Yes WebView Android Yes Samsung Internet Yes Opera Android Yes

The crossorigin attribute is a CORS settings attribute. Its purpose is to allow images from third-party sites that allow cross-origin access to be used with canvas .

The referrerpolicy attribute is a referrer policy attribute. Its purpose is to set the referrer policy used when fetching the image. [REFERRERPOLICY]

The decoding attribute indicates the preferred method to decode this image. The attribute, if present, must be an image decoding hint. This attribute's missing value default and invalid value default are both the auto state.

The loading attribute is a lazy loading attribute. Its purpose is to indicate the policy for loading images that are outside the viewport.

When the loading attribute's state is changed to the Eager state, the user agent must run these steps:

< img src = "1.jpeg" alt = "1" > < img src = "2.jpeg" loading = eager alt = "2" > < img src = "3.jpeg" loading = lazy alt = "3" > < div id = very-large ></ div > <!-- Everything after this div is below the viewport --> < img src = "4.jpeg" alt = "4" > < img src = "5.jpeg" loading = lazy alt = "5" > In the example above, the images load as follows: 1.jpeg , 2.jpeg , 4.jpeg The images load eagerly and delay the window's load event. 3.jpeg The image loads when layout is known, due to being in the viewport, however it does not delay the window's load event. 5.jpeg The image loads only once scrolled into the viewport, and does not delay the window's load event. Developers are encouraged to specify an intrinsic aspect ratio via width and height attributes on lazy loaded images, even if CSS sets the image's width and height properties, to prevent the page layout from shifting around after the image loads.

The img element must not be used as a layout tool. In particular, img elements should not be used to display transparent images, as such images rarely convey meaning and rarely add anything useful to the document.

What an img element represents depends on the src attribute and the alt attribute.

If the src attribute is set and the alt attribute is set to the empty string The image is either decorative or supplemental to the rest of the content, redundant with some other information in the document. If the image is available and the user agent is configured to display that image, then the element represents the element's image data. Otherwise, the element represents nothing, and may be omitted completely from the rendering. User agents may provide the user with a notification that an image is present but has been omitted from the rendering. If the src attribute is set and the alt attribute is set to a value that isn't empty The image is a key part of the content; the alt attribute gives a textual equivalent or replacement for the image. If the image is available and the user agent is configured to display that image, then the element represents the element's image data. Otherwise, the element represents the text given by the alt attribute. User agents may provide the user with a notification that an image is present but has been omitted from the rendering. If the src attribute is set and the alt attribute is not The image might be a key part of the content, and there is no textual equivalent of the image available. In a conforming document, the absence of the alt attribute indicates that the image is a key part of the content but that a textual replacement for the image was not available when the image was generated. If the image is available and the user agent is configured to display that image, then the element represents the element's image data. If the image has a src attribute whose value is the empty string, then the element represents nothing. Otherwise, the user agent should display some sort of indicator that there is an image that is not being rendered, and may, if requested by the user, or if so configured, or when required to provide contextual information in response to navigation, provide caption information for the image, derived as follows: If the image has a title attribute whose value is not the empty string, then return the value of that attribute. If the image is a descendant of a figure element that has a child figcaption element, and, ignoring the figcaption element and its descendants, the figure element has no flow content descendants other than inter-element whitespace and the img element, then return the contents of the first such figcaption element. Return nothing. (There is no caption information.) If the src attribute is not set and either the alt attribute is set to the empty string or the alt attribute is not set at all The element represents nothing. Otherwise The element represents the text given by the alt attribute.

The alt attribute does not represent advisory information. User agents must not present the contents of the alt attribute in the same way as content of the title attribute.

User agents may always provide the user with the option to display any image, or to prevent any image from being displayed. User agents may also apply heuristics to help the user make use of the image when the user is unable to see it, e.g. due to a visual disability or because they are using a text terminal with no graphics capabilities. Such heuristics could include, for instance, optical character recognition (OCR) of text found within the image.

While user agents are encouraged to repair cases of missing alt attributes, authors must not rely on such behavior. Requirements for providing text to act as an alternative for images are described in detail below.

The contents of img elements, if any, are ignored for the purposes of rendering.

The usemap attribute, if present, can indicate that the image has an associated image map.

The ismap attribute, when used on an element that is a descendant of an a element with an href attribute, indicates by its presence that the element provides access to a server-side image map. This affects how events are handled on the corresponding a element.

The ismap attribute is a boolean attribute. The attribute must not be specified on an element that does not have an ancestor a element with an href attribute.

The usemap and ismap attributes can result in confusing behavior when used together with source elements with the media attribute specified in a picture element.

The img element supports dimension attributes.

✔ MDN HTMLImageElement/alt Support in all current engines. Firefox Yes Safari Yes Chrome 1+ Opera Yes Edge 79+ Edge (Legacy) 12+ Internet Explorer ? Firefox Android Yes Safari iOS Yes Chrome Android Yes WebView Android Yes Samsung Internet Yes Opera Android ? HTMLImageElement/src Support in all current engines. Firefox Yes Safari Yes Chrome 1+ Opera Yes Edge 79+ Edge (Legacy) 12+ Internet Explorer ? Firefox Android Yes Safari iOS Yes Chrome Android Yes WebView Android Yes Samsung Internet Yes Opera Android Yes HTMLImageElement/srcset Support in all current engines. Firefox 38+ Safari 8+ Chrome 34+ Opera 21+ Edge 79+ Edge (Legacy) 12+ Internet Explorer No Firefox Android 38+ Safari iOS 8+ Chrome Android 34+ WebView Android 37+ Samsung Internet 2.0+ Opera Android No HTMLImageElement/sizes Firefox 38+ Safari No Chrome 45+ Opera Yes Edge 79+ Edge (Legacy) 13+ Internet Explorer No Firefox Android 38+ Safari iOS No Chrome Android 45+ WebView Android 45+ Samsung Internet 5.0+ Opera Android No

The alt , src , srcset and sizes IDL attributes must reflect the respective content attributes of the same name.

✔ MDN HTMLImageElement/crossOrigin Support in all current engines. Firefox Yes Safari Yes Chrome 13+ Opera Yes Edge 79+ Edge (Legacy) 12+ Internet Explorer 9+ Firefox Android Yes Safari iOS Yes Chrome Android Yes WebView Android Yes Samsung Internet Yes Opera Android ?

The crossOrigin IDL attribute must reflect the crossorigin content attribute, limited to only known values.

✔ MDN HTMLImageElement/useMap Support in all current engines. Firefox Yes Safari Yes Chrome 1+ Opera Yes Edge 79+ Edge (Legacy) 12+ Internet Explorer ? Firefox Android Yes Safari iOS Yes Chrome Android Yes WebView Android Yes Samsung Internet Yes Opera Android Yes

The useMap IDL attribute must reflect the usemap content attribute.

✔ MDN HTMLImageElement/isMap Support in all current engines. Firefox Yes Safari Yes Chrome 1+ Opera Yes Edge 79+ Edge (Legacy) 12+ Internet Explorer ? Firefox Android Yes Safari iOS Yes Chrome Android Yes WebView Android Yes Samsung Internet Yes Opera Android ?

The isMap IDL attribute must reflect the ismap content attribute.

The referrerPolicy IDL attribute must reflect the referrerpolicy content attribute, limited to only known values.

✔ MDN HTMLImageElement/decoding Support in all current engines. Firefox 63+ Safari 11.1+ Chrome 65+ Opera Yes Edge 79+ Edge (Legacy) No Internet Explorer No Firefox Android 63+ Safari iOS 11.3+ Chrome Android 65+ WebView Android 65+ Samsung Internet 9.0+ Opera Android ?

The decoding IDL attribute must reflect the decoding content attribute, limited to only known values.

The loading IDL attribute must reflect the loading content attribute, limited to only known values.

image . width [ = value ] image . height [ = value ] These attributes return the actual rendered dimensions of the image, or zero if the dimensions are not known. They can be set, to change the corresponding content attributes. image . naturalWidth image . naturalHeight These attributes return the intrinsic dimensions of the image, or zero if the dimensions are not known. image . complete Returns true if the image has been completely downloaded or if no image is specified; otherwise, returns false. image . currentSrc Returns the image's absolute URL. image . decode () This method causes the user agent to decode the image in parallel, returning a promise that fulfills when decoding is complete. The promise will be rejected with an " EncodingError " DOMException if the image cannot be decoded. image = new Image ( [ width [, height ] ] ) Returns a new img element, with the width and height attributes set to the values passed in the relevant arguments, if applicable.

✔ MDN HTMLImageElement/width Support in all current engines. Firefox Yes Safari Yes Chrome 1+ Opera Yes Edge 79+ Edge (Legacy) 12+ Internet Explorer ? Firefox Android Yes Safari iOS Yes Chrome Android Yes WebView Android Yes Samsung Internet Yes Opera Android Yes HTMLImageElement/height Support in all current engines. Firefox Yes Safari Yes Chrome 1+ Opera Yes Edge 79+ Edge (Legacy) 12+ Internet Explorer ? Firefox Android Yes Safari iOS Yes Chrome Android Yes WebView Android Yes Samsung Internet Yes Opera Android ?

The IDL attributes width and height must return the rendered width and height of the image, in CSS pixels, if the image is being rendered, and is being rendered to a visual medium; or else the density-corrected intrinsic width and height of the image, in CSS pixels, if the image has intrinsic dimensions and is available but not being rendered to a visual medium; or else 0, if the image is not available or does not have intrinsic dimensions. [CSS]

On setting, they must act as if they reflected the respective content attributes of the same name.

✔ MDN HTMLImageElement/naturalWidth Support in all current engines. Firefox Yes Safari Yes Chrome 1+ Opera Yes Edge 79+ Edge (Legacy) 12+ Internet Explorer 9+ Firefox Android Yes Safari iOS Yes Chrome Android Yes WebView Android Yes Samsung Internet Yes Opera Android ? caniuse.com table HTMLImageElement/naturalHeight Support in all current engines. Firefox Yes Safari Yes Chrome 1+ Opera Yes Edge 79+ Edge (Legacy) 12+ Internet Explorer 9+ Firefox Android Yes Safari iOS Yes Chrome Android Yes WebView Android Yes Samsung Internet Yes Opera Android ?

The IDL attributes naturalWidth and naturalHeight must return the density-corrected intrinsic width and height of the image, in CSS pixels, if the image has intrinsic dimensions and is available, or else 0. [CSS]

Since the intrinsic dimensions of an image take into account any orientation specified in its metadata, naturalWidth and naturalHeight reflect the dimensions after applying any rotation needed to correctly orient the image, regardless of the value of the 'image-orientation' property.

✔ MDN HTMLImageElement/complete Support in all current engines. Firefox Yes Safari Yes Chrome 1+ Opera Yes Edge 79+ Edge (Legacy) 12+ Internet Explorer 8+ Firefox Android Yes Safari iOS Yes Chrome Android Yes WebView Android Yes Samsung Internet Yes Opera Android ?

The IDL attribute complete must return true if any of the following conditions is true:

Otherwise, the attribute must return false.

✔ MDN HTMLImageElement/currentSrc Support in all current engines. Firefox 38+ Safari 10.1+ Chrome 45+ Opera Yes Edge 79+ Edge (Legacy) 13+ Internet Explorer No Firefox Android 38+ Safari iOS 10.3+ Chrome Android 45+ WebView Android 45+ Samsung Internet 5.0+ Opera Android No

The currentSrc IDL attribute must return the img element's current request's current URL.

✔ MDN HTMLImageElement/decode Support in all current engines. Firefox 68+ Safari 11.1+ Chrome 64+ Opera Yes Edge 79+ Edge (Legacy) No Internet Explorer No Firefox Android 68+ Safari iOS 11.3+ Chrome Android 64+ WebView Android 64+ Samsung Internet 9.0+ Opera Android ? SVGImageElement/decode Support in one engine only. Firefox No Safari ? Chrome 65+ Opera ? Edge 79+ Edge (Legacy) No Internet Explorer ? Firefox Android No Safari iOS ? Chrome Android 65+ WebView Android 65+ Samsung Internet 9.0+ Opera Android ?

The decode() method, when invoked, must perform the following steps:

Without the decode() method, the process of loading an img element and then displaying it might look like the following: const img = new Image (); img . src = "nebula.jpg" ; img . onload = () => { document . body . appendChild ( img ); }; img . onerror = () => { document . body . appendChild ( new Text ( "Could not load the nebula :(" )); }; However, this can cause notable dropped frames, as the paint that occurs after inserting the image into the DOM causes a synchronous decode on the main thread. This can instead be rewritten using the decode() method: const img = new Image (); img . src = "nebula.jpg" ; img . decode (). then (() => { document . body . appendChild ( img ); }). catch (() => { document . body . appendChild ( new Text ( "Could not load the nebula :(" )); }); This latter form avoids the dropped frames of the original, by allowing the user agent to decode the image in parallel, and only inserting it into the DOM (and thus causing it to be painted) once the decoding process is complete.

Because the decode() method attempts to ensure that the decoded image data is available for at least one frame, it can be combined with the requestAnimationFrame() API. This means it can be used with coding styles or frameworks that ensure that all DOM modifications are batched together as animation frame callbacks: const container = document . querySelector ( "#container" ); const { containerWidth , containerHeight } = computeDesiredSize (); requestAnimationFrame (() => { container . style . width = containerWidth ; container . style . height = containerHeight ; }); // ... const img = new Image (); img . src = "supernova.jpg" ; img . decode (). then (() => { requestAnimationFrame (() => container . appendChild ( img )); });

✔ MDN HTMLImageElement/Image Support in all current engines. Firefox 1+ Safari 10.1+ Chrome 1+ Opera 8+ Edge 79+ Edge (Legacy) 12+ Internet Explorer 8+ Firefox Android 4+ Safari iOS 1+ Chrome Android 18+ WebView Android 1+ Samsung Internet 1.0+ Opera Android ?

A legacy factory function is provided for creating HTMLImageElement objects (in addition to the factory methods from DOM such as createElement() ): Image( width , height ) . When invoked, the legacy factory function must perform the following steps:

A single image can have different appropriate alternative text depending on the context. In each of the following cases, the same image is used, yet the alt text is different each time. The image is the coat of arms of the Carouge municipality in the canton Geneva in Switzerland. Here it is used as a supplementary icon: < p > I lived in < img src = "carouge.svg" alt = "" > Carouge. </ p > Here it is used as an icon representing the town: < p > Home town: < img src = "carouge.svg" alt = "Carouge" ></ p > Here it is used as part of a text on the town: < p > Carouge has a coat of arms. </ p > < p >< img src = "carouge.svg" alt = "The coat of arms depicts a lion, sitting in front of a tree." ></ p > < p > It is used as decoration all over the town. </ p > Here it is used as a way to support a similar text where the description is given as well as, instead of as an alternative to, the image: < p > Carouge has a coat of arms. </ p > < p >< img src = "carouge.svg" alt = "" ></ p > < p > The coat of arms depicts a lion, sitting in front of a tree. It is used as decoration all over the town. </ p > Here it is used as part of a story: < p > She picked up the folder and a piece of paper fell out. </ p > < p >< img src = "carouge.svg" alt = "Shaped like a shield, the paper had a red background, a green tree, and a yellow lion with its tongue hanging out and whose tail was shaped like an S." ></ p > < p > She stared at the folder. S! The answer she had been looking for all this time was simply the letter S! How had she not seen that before? It all came together now. The phone call where Hector had referred to a lion's tail, the time Maria had stuck her tongue out... </ p > Here it is not known at the time of publication what the image will be, only that it will be a coat of arms of some kind, and thus no replacement text can be provided, and instead only a brief caption for the image is provided, in the title attribute: < p > The last user to have uploaded a coat of arms uploaded this one: </ p > < p >< img src = "last-uploaded-coat-of-arms.cgi" title = "User-uploaded coat of arms." ></ p > Ideally, the author would find a way to provide real replacement text even in this case, e.g. by asking the previous user. Not providing replacement text makes the document more difficult to use for people who are unable to view images, e.g. blind users, or users or very low-bandwidth connections or who pay by the byte, or users who are forced to use a text-only web browser.