GeezerVison

1. 1. 4.8 Embedded content
      1. 4.8.1 The picture element
      2. 4.8.2 The source element
      3. 4.8.3 The img element

4.8 Embedded content

4.8.1 The picture element

Categories:

Flow content.

Phrasing content.

Embedded content.

Palpable content.

Contexts in which this element can be used:

Where embedded content is expected.

Content model:

Zero or more source elements, followed by one img element, optionally intermixed with script-supporting elements.

Tag omission in text/html:

Neither tag is omissible.

Content attributes:

Global attributes

Accessibility considerations:

For authors.

For implementers.

Sanitization:

Uncategorized.

DOM interface:

[Exposed=Window]
interface HTMLPictureElement : HTMLElement {
  [HTMLConstructor] constructor();
};

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

Categories:

None.

Contexts in which this element can be used:

As a child of a picture element, before the img element.

As a child of a media element, before any flow content or track elements.

Content model:

Nothing.

Tag omission in text/html:

No end tag.

Content attributes:

Global attributes

type — Type of embedded resource

media — Applicable media

src (in audio or video) — Address of the resource

srcset (in picture) — Images to use in different situations, e.g., high-resolution displays, small monitors, etc.

sizes (in picture) — Image sizes for different page layouts

width (in picture) — Horizontal dimension

height (in picture) — Vertical dimension

Accessibility considerations:

For authors.

For implementers.

Sanitization:

Uncategorized.

DOM interface:

[Exposed=Window]
interface HTMLSourceElement : HTMLElement {
  [HTMLConstructor] constructor();

  [CEReactions, ReflectURL] attribute USVString src;
  [CEReactions, Reflect] attribute DOMString type;
  [CEReactions, Reflect] attribute USVString srcset;
  [CEReactions, Reflect] attribute DOMString sizes;
  [CEReactions, Reflect] attribute DOMString media;
  [CEReactions, Reflect] attribute unsigned long width;
  [CEReactions, Reflect] attribute unsigned long height;
};

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 media attribute may also be present. If present, the value must contain a valid media query list. The user agent will skip to the next source element if the value does not match the environment.

The media attribute is only evaluated once during the resource selection algorithm for media elements. In contrast, when using the picture element, the user agent will react to changes in the environment.

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

The source element's parent is a picture element

The srcset attribute must be present, and is a srcset attribute.

The srcset attribute contributes the image sources to the source set, if the source element is selected.

If the srcset attribute has any image candidate strings using a width descriptor, the sizes attribute may also be present. If, additionally, the following sibling img element does not allow auto-sizes, the sizes attribute must be present. The sizes attribute is a sizes attribute, which contributes the source size to the source set, if the source element is selected.

If the img element allows auto-sizes, then the sizes attribute can be omitted on previous sibling source elements. In such cases, it is equivalent to specifying auto.

The source element supports dimension attributes. The img element can use the width and height attributes of a source element, instead of those on the img element itself, to determine its rendered dimensions and aspect-ratio, as defined in the Rendering section.

The type attribute gives the type of the images in the source set, to allow the user agent to skip to the next source element if it does not support the given type.

If the type attribute is not specified, the user agent will not select a different source element if it finds that it does not support the image format after fetching it.

When a source element has a following sibling source element or img element with a srcset attribute specified, it must have at least one of the following:

• A media attribute specified with a value that, after stripping leading and trailing ASCII whitespace, is not the empty string and is not an ASCII case-insensitive match for the string "all".

• A type attribute specified.

The src attribute must not be present.

The source element's parent is a media element

The src attribute gives the URL of the media resource. The value must be a valid non-empty URL potentially surrounded by spaces. This attribute must be present.

The type attribute gives the type of the media resource, to help the user agent determine if it can play this media resource before fetching it. The codecs parameter, which certain MIME types define, might be necessary to specify exactly how the resource is encoded. [RFC6381]

Dynamically modifying a source element's src or type attribute when the element is already inserted in a video or audio element will have no effect. To change what is playing, just use the src attribute on the media element directly, possibly making use of the canPlayType() method to pick from amongst available resources. Generally, manipulating source elements manually after the document has been parsed is an unnecessarily complicated approach.

The following list shows some examples of how to use the codecs= MIME parameter in the type attribute.

H.264 Constrained baseline profile video (main and extended video compatible) level 3 and Low-Complexity AAC audio in MP4 container

<source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'>

H.264 Extended profile video (baseline-compatible) level 3 and Low-Complexity AAC audio in MP4 container

<source src='video.mp4' type='video/mp4; codecs="avc1.58A01E, mp4a.40.2"'>

H.264 Main profile video level 3 and Low-Complexity AAC audio in MP4 container

<source src='video.mp4' type='video/mp4; codecs="avc1.4D401E, mp4a.40.2"'>

H.264 'High' profile video (incompatible with main, baseline, or extended profiles) level 3 and Low-Complexity AAC audio in MP4 container

<source src='video.mp4' type='video/mp4; codecs="avc1.64001E, mp4a.40.2"'>

MPEG-4 Visual Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container

<source src='video.mp4' type='video/mp4; codecs="mp4v.20.8, mp4a.40.2"'>

MPEG-4 Advanced Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container

<source src='video.mp4' type='video/mp4; codecs="mp4v.20.240, mp4a.40.2"'>

MPEG-4 Visual Simple Profile Level 0 video and AMR audio in 3GPP container

<source src='video.3gp' type='video/3gpp; codecs="mp4v.20.8, samr"'>

Theora video and Vorbis audio in Ogg container

<source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'>

Theora video and Speex audio in Ogg container

<source src='video.ogv' type='video/ogg; codecs="theora, speex"'>

Vorbis audio alone in Ogg container

<source src='audio.ogg' type='audio/ogg; codecs=vorbis'>

Speex audio alone in Ogg container

<source src='audio.spx' type='audio/ogg; codecs=speex'>

FLAC audio alone in Ogg container

<source src='audio.oga' type='audio/ogg; codecs=flac'>

Dirac video and Vorbis audio in Ogg container

<source src='video.ogv' type='video/ogg; codecs="dirac, vorbis"'>

The srcset and sizes attributes must not be present.

<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

Categories:

Flow content.

Phrasing content.

Embedded content.

Form-associated element.

If the element has a usemap or controls attribute: Interactive content.

Palpable content.

Contexts in which this element can be used:

Where embedded content is expected.

As a child of a picture element, after all source elements.

Content model:

Nothing.

Tag omission in text/html:

No end tag.

Content attributes:

Global attributes

alt — Replacement text for use when images are not available

src — Address of the resource

srcset — Images to use in different situations, e.g., high-resolution displays, small monitors, etc.

sizes — Image sizes for different page layouts

crossorigin — How the element handles crossorigin requests

usemap — Name of image map to use

ismap — Whether the image is a server-side image map

controls — Show user agent controls

width — Horizontal dimension

height — Vertical dimension

referrerpolicy — Referrer policy for fetches initiated by the element

decoding — Decoding hint to use when processing this image for presentation

loading — Used when determining loading deferral

fetchpriority — Sets the priority for fetches initiated by the element

Accessibility considerations:

If the element has a non-empty alt attribute: for authors; for implementers.

Otherwise: for authors; for implementers.

Sanitization:

Uncategorized.

DOM interface:

[Exposed=Window,
 LegacyFactoryFunction=Image(optional unsigned long width, optional unsigned long height)]
interface HTMLImageElement : HTMLElement {
  [HTMLConstructor] constructor();

  [CEReactions, Reflect] attribute DOMString alt;
  [CEReactions, ReflectURL] attribute USVString src;
  [CEReactions, Reflect] attribute USVString srcset;
  [CEReactions, Reflect] attribute DOMString sizes;
  [CEReactions] attribute DOMString? crossOrigin;
  [CEReactions, Reflect] attribute DOMString useMap;
  [CEReactions, Reflect] attribute boolean isMap;
  [CEReactions, Reflect] attribute boolean controls;
  [CEReactions, ReflectSetter] attribute unsigned long width;
  [CEReactions, ReflectSetter] attribute unsigned long height;
  readonly attribute unsigned long naturalWidth;
  readonly attribute unsigned long naturalHeight;
  readonly attribute boolean complete;
  readonly attribute USVString currentSrc;
  [CEReactions] attribute DOMString referrerPolicy;
  [CEReactions] attribute DOMString decoding;
  [CEReactions] attribute DOMString loading;
  [CEReactions] attribute DOMString fetchPriority;

  Promise<undefined> decode();

  // also has obsolete members
};

An img element represents an image.

An img element has a dimension attribute source, initially set to the element itself.

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.

At least one of the src and srcset attributes must be present.

If the src attribute is present, it 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 the like. [PNG] [GIF] [JPEG] [PDF] [XML] [APNG] [SVG] [MNG]

The srcset attribute 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 image candidate strings using a width descriptor, the sizes attribute must also be present. If the srcset attribute is not specified, and the loading attribute is in the Lazy state, the sizes attribute may be specified with the value "auto" (ASCII case-insensitive). The sizes attribute is a sizes attribute, which contributes the source size to the source set (if no source element was selected).

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 fetchpriority attribute is a fetch priority attribute. Its purpose is to set the priority used when fetching the image.

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

<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">

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.

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 controls attribute is a boolean attribute. If present, it indicates that the user agent may expose a user interface to the user. The attribute must not be specified on an element that does not have an alt attribute, or whose alt attribute's value is the empty string.

If the controls attribute is present, the user agent may expose controls over the image (e.g., a control for fullscreen viewing). The specific controls provided are implementation-defined, and can be platform-specific or based on the user's preferences.

If the user agent exposes a user interface by displaying controls over the img element, then the user agent should suppress any user interaction events while the user agent is interacting with this interface.

Issue #12318 tracks the interaction between image controls and animated images. User agents should not expose animation controls for images before that issue is resolved.

The img element supports dimension attributes.

image.width [ = value ]

HTMLImageElement/width

Support in all current engines.

Firefox1+Safari3+Chrome1+

---

Opera12.1+Edge79+

---

Edge (Legacy)12+Internet Explorer5.5+

---

Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+

image.height [ = value ]

HTMLImageElement/height

Support in all current engines.

Firefox1+Safari3+Chrome1+

---

Opera12.1+Edge79+

---

Edge (Legacy)12+Internet Explorer5.5+

---

Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+

These attributes return the rendered dimensions of the image. When the image is not being rendered, they return the width and height content attributes' values, defaulting to naturalWidth and naturalHeight.

They can be set, to change the corresponding content attributes.

image.naturalWidth

HTMLImageElement/naturalWidth

Support in all current engines.

Firefox1+Safari3+Chrome1+

---

Opera12.1+Edge79+

---

Edge (Legacy)12+Internet Explorer9+

---

Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+

image.naturalHeight

HTMLImageElement/naturalHeight

Support in all current engines.

Firefox1+Safari3+Chrome1+

---

Opera12.1+Edge79+

---

Edge (Legacy)12+Internet Explorer9+

---

Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+

These attributes return the density-corrected natural width and height of the image, or 0 if the image is not available.

image.complete

HTMLImageElement/complete

Support in all current engines.

Firefox1+Safari3+Chrome1+

---

Opera12.1+Edge79+

---

Edge (Legacy)12+Internet Explorer5.5+

---

Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+

Returns true if the image has been completely downloaded or if no image is specified; otherwise, returns false.

image.currentSrc

HTMLImageElement/currentSrc

Support in all current engines.

Firefox38+Safari9.1+Chrome38+

---

Opera?Edge79+

---

Edge (Legacy)13+Internet ExplorerNo

---

Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?

Returns the image's absolute URL.

image.decode()

HTMLImageElement/decode

Support in all current engines.

Firefox68+Safari11.1+Chrome64+

---

Opera?Edge79+

---

Edge (Legacy)?Internet ExplorerNo

---

Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?

SVGImageElement/decode

Firefox68+SafariNoChrome64+

---

Opera?Edge79+

---

Edge (Legacy)?Internet ExplorerNo

---

Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?

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 ] ])

HTMLImageElement/Image

Support in all current engines.

Firefox1+Safari1+Chrome1+

---

Opera8+Edge79+

---

Edge (Legacy)12+Internet Explorer5.5+

---

Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+

Returns a new img element, with the width and height attributes set to the values passed in the relevant arguments, if applicable.

Since the density-corrected natural width and height 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.

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 :("));
};

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 :("));
});

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));
});

<p>I lived in <img src="carouge.svg" alt=""> Carouge.</p>

<p>Home town: <img src="carouge.svg" alt="Carouge"></p>

<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>

<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>

<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>

<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>

<article>
 <h1>My cats</h1>
 <h2>Fluffy</h2>
 <p>Fluffy is my favorite.</p>
 <img src="fluffy.jpg" alt="She likes playing with a ball of yarn.">
 <p>She's just too cute.</p>
 <h2>Miles</h2>
 <p>My other cat, Miles just eats and sleeps.</p>
</article>

<article>
 <h1>Photography</h1>
 <h2>Shooting moving targets indoors</h2>
 <p>The trick here is to know how to anticipate; to know at what speed and
 what distance the subject will pass by.</p>
 <img src="fluffy.jpg" alt="A cat flying by, chasing a ball of yarn, can be
 photographed quite nicely using this technique.">
 <h2>Nature by night</h2>
 <p>To achieve this, you'll need either an extremely sensitive film, or
 immense flash lights.</p>
</article>

<article>
 <h1>About me</h1>
 <h2>My pets</h2>
 <p>I've got a cat named Fluffy and a dog named Miles.</p>
 <img src="fluffy.jpg" alt="Fluffy, my cat, tends to keep itself busy.">
 <p>My dog Miles and I like go on long walks together.</p>
 <h2>music</h2>
 <p>After our walks, having emptied my mind, I like listening to Bach.</p>
</article>

<article>
 <h1>Fluffy and the Yarn</h1>
 <p>Fluffy was a cat who liked to play with yarn. She also liked to jump.</p>
 <aside><img src="fluffy.jpg" alt="" title="Fluffy"></aside>
 <p>She would play in the morning, she would play in the evening.</p>
</article>