HTML 5.3

4.7. Embedded content

4.7.1. Introduction

This section is non-normative.

To embed an image in HTML, when there is only a single image resource, use the img element and with its src and alt attributes.

<h2>From today’s featured article</h2>
<img src="/uploads/100-marie-lloyd.jpg" alt="A singer on the stage" width="100" height="150">
<p><a href="/wiki/Marie_Lloyd">Marie Lloyd</a> (1870–1922)
was an English <a href="/wiki/Music_hall">music hall</a> singer, ...

However, there are a number of situations for which the author might wish to use multiple image resources that the user agent can choose from:

• Different users might have different environmental characteristics:

  • The users' physical screen size might be different from one another.

    A mobile phone’s screen might be 4 inches diagonally, while a laptop’s screen might be 14 inches diagonally.

    

    This is only relevant when an image’s rendered size depends on the viewport size.

  • The users' screen pixel density might be different from one another.

    A mobile phone’s screen might have three times as many physical pixels per inch compared to another mobile phone’s screen, regardless of their physical screen size.

    

  • The users' zoom level might be different from one another, or might change for a single user over time.

    A user might zoom in to a particular image to be able to get a more detailed look.

    The zoom level and the screen pixel density (the previous point) can both affect the number of physical screen pixels per CSS pixel. This ratio is usually referred to as device-pixel-ratio.

  • The users' screen orientation might be different from one another, or might change for a single user over time.

    A tablet can be held upright or rotated 90 degrees, so that the screen is either "portrait" or "landscape".

    

  • The users' network speed, network latency and bandwidth cost might be different from one another, or might change for a single user over time.

    A user might be on a fast, low-latency and constant-cost connection while at work, on a slow, low-latency and constant-cost connection while at home, and on a variable-speed, high-latency and variable-cost connection anywhere else.

• Authors might want to show the same image content but with different rendered size depending on, usually, the width of the viewport. This is usually referred to as viewport-based selection.

  A Web page might have a banner at the top that always spans the entire viewport width. In this case, the rendered size of the image depends on the physical size of the screen (assuming a maximised browser window).

  

  Another Web page might have images in columns, with a single column for screens with a small physical size, two columns for screens with medium physical size, and three columns for screens with big physical size, with the images varying in rendered size in each case to fill up the viewport. In this case, the rendered size of an image might be bigger in the one-column layout compared to the two-column layout, despite the screen being smaller.

  

• Authors might want to show different image content depending on the rendered size of the image. This is usually referred to as art direction.

  When a Web page is viewed on a screen with a large physical size (assuming a maximised browser window), the author might wish to include some less relevant parts surrounding the critical part of the image. When the same Web page is viewed on a screen with a small physical size, the author might wish to show only the critical part of the image.

  

• Authors might want to show the same image content but using different image formats, depending on which image formats the user agent supports. This is usually referred to as image format-based selection.

  A Web page might have some images in the JPEG, WebP and JPEG XR image formats, as the latter two have better compression abilities compared to JPEG. Since different user agents can support different image formats, with some formats offering better compression ratios, the author would like to serve the better formats to user agents that support them, while providing a JPEG fallback for user agents that don’t.

The above situations are not mutually exclusive. For example, it is reasonable to combine different resources for different device-pixel-ratio with different resources for art direction.

While it is possible to solve these problems using scripting, doing so introduces some other problems:

• Some user agents aggressively download images specified in the HTML markup, before scripts have had a chance to run, so that Web pages complete loading sooner. If a script changes which image to download, the user agent will potentially start two separate downloads, which can instead cause worse page loading performance.
• If the author avoids specifying any image in the HTML markup and instead instantiates a single download from script, that avoids the double download problem above but instead it makes no image be downloaded at all for users with scripting disabled and it disables the aggressive image downloading optimization.

With this in mind, this specification introduces a number of features to address the above problems in a declarative manner.

Device-pixel-ratio-based selection when the rendered size of the image is fixed

The src and srcset attributes on the img element can be used, using the x descriptor, to provide multiple images that only vary in their size (the smaller image is a scaled-down version of the bigger image).

The x descriptor is not appropriate when the rendered size of the image depends on the viewport width (viewport-based selection), but can be used together with art direction.

<h2>From today’s featured article</h2>
<img src="/uploads/100-marie-lloyd.jpg"
    srcset="/uploads/150-marie-lloyd.jpg 1.5x, /uploads/200-marie-lloyd.jpg 2x"
    alt="A singer on the stage" width="100" height="150">
<p>
  <a href="/wiki/Marie_Lloyd">Marie Lloyd</a> (1870–1922)
  was an English <a href="/wiki/Music_hall">music hall</a> singer, ...

The user agent can choose any of the given resources depending on the user’s screen’s pixel density, zoom level, and possibly other factors such as the user’s network conditions.

To provide backwards compatibility with older user agents that don’t understand the srcset attribute, one of the URLs is specified in the img element’s src attribute. This will result in something useful (though perhaps at a lower-resolution than the user might expect) being displayed even in older user agents. For user agents that understand srcset, the src attribute participates in the resource selection, as if it had been specified by srcset with a 1x descriptor.

The image’s rendered size is given in the width and height attributes, which allows the user agent to allocate space for the image before it is downloaded.

Viewport-based selection

The srcset and sizes attributes can be used, using the w descriptor, to provide multiple images that only vary in their size (the smaller image is a scaled-down version of the bigger image).

In this example, a banner image takes up the entire viewport width (using appropriate CSS).

<h1>
  <img srcset="wolf-400.jpg 400w, wolf-800.jpg 800w, wolf-1600.jpg 1600w"
    src="wolf-400.jpg" sizes="100vw" alt="The rad wolf">
</h1>

The user agent will calculate the effective pixel density of each image from the specified w descriptors and the specified rendered size in the sizes attribute. It can then choose any of the given resources depending on the user’s screen’s pixel density, zoom level, and possibly other factors such as the user’s network conditions.

If the user’s screen is 320 CSS pixels wide, this is equivalent to specifying wolf-400.jpg 1.25x, wolf-800.jpg 2.5x, wolf-1600.jpg 5x. On the other hand, if the user’s screen is 1200 CSS pixels wide, this is equivalent to specifying wolf-400.jpg 0.33x, wolf-800.jpg 0.67x, wolf-1600.jpg 1.33x. By using the w descriptors and the sizes attribute, the user agent can choose the correct image source to download regardless of how large the user’s device is.

For backwards compatibility, one of the URLs is specified in the img element’s src attribute. In new user agents, the src attribute is ignored when the srcset attribute uses w descriptors.

In this example, the sizes attribute could be omitted because the default value is 100vw.

In this example, the Web page has three layouts depending on the width of the viewport. The narrow layout has one column of images (the width of each image is about 100%), the middle layout has two columns of images (the width of each image is about 50%), and the widest layout has three columns of images, and some page margin (the width of each image is about 33%). It breaks between these layouts when the viewport is 30em wide and 50em wide, respectively.

<img sizes="(max-width: 30em) 100vw, (max-width: 50em) 50vw, calc(33vw - 100px)"
srcset="swing-200.jpg 200w, swing-400.jpg 400w, swing-800.jpg 800w, swing-1600.jpg 1600w"
src="swing-400.jpg" alt="Kettlebell Swing">

The sizes attribute sets up the layout breakpoints at 30em and 50em, and declares the image sizes between these breakpoints to be 100vw, 50vw, or calc(33vw - 100px). These sizes do not necessarily have to match up exactly with the actual image width as specified in the CSS.

The user agent will pick a width from the sizes attribute, using the first item with a <media-condition> (the part in parentheses) that evaluates to true, or using the last item (calc(33vw - 100px)) if they all evaluate to false.

For example, if the viewport width is 29em, then (max-width: 30em) evaluates to true and 100vw is used, so the image size, for the purpose of resource selection, is 29em. If the viewport width is instead 32em, then (max-width: 30em) evaluates to false, but (max-width: 50em) evaluates to true and 50vw is used, so the image size, for the purpose of resource selection, is 16em (half the viewport width). Notice that the slightly wider viewport results in a smaller image because of the different layout.

The user agent can then calculate the effective pixel density and choose an appropriate resource similarly to the previous example.

Art direction-based selection

The picture element and the source element, together with the media attribute, can be used, to provide multiple images that vary the image content (for instance the smaller image might be a cropped version of the bigger image).

<picture>
  <source media="(min-width: 45em)" srcset="large.jpg">
  <source media="(min-width: 32em)" srcset="med.jpg">
  <img src="small.jpg" alt="The wolf runs through the snow.">
</picture>

The user agent will choose the first source element for which the media query in the media attribute matches, and then choose an appropriate URL from its srcset attribute.

The rendered size of the image varies depending on which resource is chosen. To specify dimensions that the user agent can use before having downloaded the image, CSS can be used.

img { width: 300px; height: 300px }
@media (min-width: 32em) { img { width: 500px; height:300px } }
@media (min-width: 45em) { img { width: 700px; height:400px } }

This example combines art direction- and device-pixel-ratio-based selection. A banner that takes half the viewport is provided in two versions, one for wide screens and one for narrow screens.

<h1>
  <picture>
    <source media="(max-width: 500px)" srcset="banner-phone.jpeg, banner-phone-HD.jpeg 2x">
    <img src="banner.jpeg" srcset="banner-HD.jpeg 2x" alt="The Breakfast Combo">
  </picture>
</h1>

Image format-based selection

The type attribute on the source element can be used, to provide multiple images in different formats.

<h2>From today’s featured article</h2>
<picture>
  <source srcset="/uploads/100-marie-lloyd.webp" type="image/webp">
  <source srcset="/uploads/100-marie-lloyd.jxr" type="image/vnd.ms-photo">
  <img src="/uploads/100-marie-lloyd.jpg" alt="A singer on the stage" width="100" height="150">
</picture>
<p>
  <a href="/wiki/Marie_Lloyd">Marie Lloyd</a> (1870–1922)
  was an English <a href="/wiki/Music_hall">music hall</a> singer, ...

In this example, the user agent will choose the first source that has a type attribute with a supported MIME type. If the user agent supports WebP images, the first source element will be chosen. If not, but the user agent does support JPEG XR images, the second source element will be chosen. If neither of those formats are supported, the img element will be chosen.

4.7.2. Dependencies

Media Queries [MEDIAQ]

<media-condition>

CSS Values and Units [CSS-VALUES]

<length>

CSS Syntax [CSS-SYNTAX-3]

Parse a comma-separated list of component values

component value

<whitespace-token>

4.7.3. The picture element

Categories:

Flow content.

Phrasing content.

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

Allowed ARIA role attribute values:

None.

Allowed ARIA state and property attributes:

None.

DOM interface:

interface HTMLPictureElement : HTMLElement {};

The picture element is a container which provides multiples 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 user agent first tries to match an image source contained within the source attribute and use that, but if none is found, it falls back to what is contained within the img element, which must be present.

<h3>
  <picture>
    <source media="(max-width: 500px)" srcset="photo-small-screen.jpg">
    <img src="photo-large-screen.jpg"" alt>
  </picture>
  Dogs & Cats, Living Together
</h3>

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.

By itself 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.7.4. 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

src - Address of the resource

type - Type of embedded resource

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

sizes - Image sizes between breakpoints

media - Applicable media

Allowed ARIA role attribute values:

None

Allowed ARIA state and property attributes:

None

DOM interface:

interface HTMLSourceElement : HTMLElement {
  attribute DOMString src;
  attribute DOMString type;
  attribute DOMString srcset;
  attribute DOMString sizes;
  attribute DOMString media;
};

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.

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

source element’s parent is a picture element

The srcset content attribute must be present, and must consist of one or more image candidate strings, each separated from the next by a U+002C COMMA character (,). If an image candidate string contains no descriptors and no space characters after the URL, the following image candidate string, if there is one, must begin with one or more space characters.

If the srcset attribute has any image candidate strings using a width descriptor, the sizes content attribute must also be present, and the value must be a valid source size list.

The media content attribute may also be present. If present, the value must contain a valid media query list.

The type 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 white space, 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.

source element’s parent is a media element

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

Dynamically modifying a source element and its 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 type content attribute gives the type of the media resource, to help the user agent determine if it can play this media resource before fetching it. If specified, its value must be a valid MIME type. The codecs parameter, which certain MIME types define, might be necessary to specify exactly how the resource is encoded. [RFC6381]

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, sizes, and media attributes must not be present.

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.

<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.7.5. The img element

Categories:

Flow content.

Phrasing content.

Embedded content.

Form-associated element.

If the element has a usemap attribute: interactive content.

Palpable content.

Contexts in which this element can be used:

Where embedded content is expected.

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

crossorigin - How the element handles crossorigin requests

decoding - Hint for requesting synchronous or asynchronous loading

usemap - Name of image map to use

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

width - Horizontal dimension

height - Vertical dimension

referrerpolicy - Referrer policy for fetches initiated by the element

longdesc - A url that provides a link to an expanded description of the image, defined in [html-longdesc]

Allowed ARIA role attribute values:

If img has an empty alt attribute value: presentation or none role only.

If img has a non-empty alt attribute value: img (default - do not set) or any other role value except presentation or none roles.

Allowed ARIA state and property attributes:

If img has an empty alt attribute value: No aria-* attributes except aria-hidden.

If img has a non-empty alt attribute value: Global aria-* attributes and any aria-* attributes applicable to the allowed roles.

DOM interface:

[NamedConstructor=Image(optional unsigned long width, optional unsigned long height)]
interface HTMLImageElement : HTMLElement {
  [CEReactions] attribute DOMString alt;
  [CEReactions] attribute DOMString src;
  [CEReactions] attribute DOMString srcset;
  [CEReactions] attribute DOMString sizes;
  [CEReactions] attribute DOMString? crossOrigin;
  [CEReactions] attribute DOMString decoding;
  [CEReactions] attribute DOMString useMap;
  attribute DOMString longDesc;
  [CEReactions] attribute boolean isMap;
  [CEReactions] attribute unsigned long width;
  [CEReactions] attribute unsigned long height;
  readonly attribute unsigned long naturalWidth;
  readonly attribute unsigned long naturalHeight;
  readonly attribute boolean complete;
  readonly attribute DOMString currentSrc;
  [CEReactions] attribute DOMString referrerPolicy;
};

An img element represents an image and its fallback content.

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 and the content referred to by the longdesc attribute are the img element’s fallback content, and provide equivalent content for users and user agents who cannot process images or have image loading disabled.

Requirements for alternative representations of the image are described in the next 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 srcset attribute may also be present. If present, its value must consist of one or more image candidate strings, each separated from the next by a U+002C COMMA character (,). If an image candidate string contains no descriptors and no space characters after the URL, the following image candidate string, if there is one, must begin with one or more space characters.

An image candidate string consists of the following components, in order, with the further restrictions described below this list:

1. Zero or more space characters.
2. A valid non-empty URL that does not start or end with a U+002C COMMA character (,), referencing a non-interactive, optionally animated, image resource that is neither paged nor scripted.
3. Zero or more space characters.

4. Zero or one of the following:

   • A width descriptor, consisting of: a space character, a valid non-negative integer giving a number greater than zero representing the width descriptor value, and a U+0077 LATIN SMALL LETTER W character.
   • A pixel density descriptor, consisting of: a space character, a valid floating-point number giving a number greater than zero representing the pixel density descriptor value, and a U+0078 LATIN SMALL LETTER X character.
5. Zero or more space characters.

There must not be an image candidate string for an element that has the same width descriptor value as another image candidate string’s width descriptor value for the same element.

There must not be an image candidate string for an element that has the same pixel density descriptor value as another image candidate string’s pixel density descriptor value for the same element. For the purpose of this requirement, an image candidate string with no descriptors is equivalent to an image candidate string with a 1x descriptor.

If a source element has a sizes attribute present or an img element has a sizes attribute present, all image candidate strings for that element must have the width descriptor specified.

If an image candidate string for a source or img element has the width descriptor specified, all other image candidate strings for that element must also have the width descriptor specified.

The specified width in an image candidate string’s width descriptor must match the intrinsic width in the resource given by the image candidate string’s URL, if it has an intrinsic width.

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] [SVG11] [MNG]

If the srcset attribute is present, the sizes attribute may also be present. If present, its value must be a valid source size list.

A valid source size list is a string that matches the following grammar: [CSS-VALUES] [MEDIAQ]

<source-size-list> = <source-size># [ , <source-size-value> ]? | <source-size-value>
<source-size> = <media-condition> <source-size-value>
<source-size-value> = <length>

A <source-size-value> must not be negative.

Percentages are not allowed in a <source-size-value>, to avoid confusion about what it would be relative to. The vw unit can be used for sizes relative to the viewport width.

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 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 decoding attribute is an enumerated attribute. It is an image decoding hint to request synchronous or asynchronous image loading. Valid values are "sync", "async", and "auto". The missing value default and invalid value default are both "auto".

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

An img element has a current request and a pending request. The current request is initially set to a new image request. The pending request is initially set to null. The current request is usually referred to as the img element itself.

An image request has a state, current URL and image data.

An image request’s state is one of the following:

Unavailable

The user agent hasn’t obtained any image data, or has obtained some or all of the image data but hasn’t yet decoded enough of the image to get the image dimensions.

Partially available

The user agent has obtained some of the image data and at least the image dimensions are available.

Completely available

The user agent has obtained all of the image data and at least the image dimensions are available.

Broken

The user agent has obtained all of the image data that it can, but it cannot even decode the image enough to get the image dimensions (e.g., the image is corrupted, or the format is not supported, or no data could be obtained).

An image request’s current URL is initially the empty string.

An image request’s image data is the decoded image data.

When an image request is either in the partially available state or in the completely available state, it is said to be available.

An image request is initially unavailable.

When an img element is available, it provides a paint source whose width is the image’s density-corrected intrinsic width (if any), whose height is the image’s density-corrected intrinsic height (if any), and whose appearance is the intrinsic appearance of the image.

In a browsing context where scripting is disabled, user agents may obtain images immediately or on demand. In a browsing context where scripting is enabled, user agents must obtain images immediately.

A user agent that obtains images immediately must immediately update the image data of an img element, with the restart animation flag set if so stated, whenever that element is created or has experienced relevant mutations.

A user agent that obtains images on demand must update the image data of an img element whenever it needs the image data (i.e., on demand), but only if the img element is in the unavailable state. When an img element has experienced relevant mutations, if the user agent only obtains images on demand, the img element must return to the unavailable state.

The relevant mutations for an img element are as follows:

• The element’s src, srcset, width, or sizes attributes are set, changed, or removed.
• The element’s src attribute is set to the same value as the previous value. This must set the restart animation flag for the update the image data algorithm.
• The element’s crossorigin attribute’s state is changed.
• The element is inserted into or removed from a picture parent element.
• The element’s parent is a picture element and a source element is inserted as a previous sibling.
• The element’s parent is a picture element and a source element that was a previous sibling is removed.
• The element’s parent is a picture element and a source element that is a previous sibling has its srcset, sizes, media or type attributes set, changed, or removed.
• The element’s adopting steps are run.

Each img element has a last selected source, which must initially be null.

Each image request has a current pixel density, which must initially be undefined.

When an img element has a current pixel density that is not 1.0, the element’s image data must be treated as if its resolution, in device pixels per CSS pixels, was the current pixel density. The image’s density-corrected intrinsic width and height are the intrinsic width and height after taking into account the current pixel density.

For example, given a screen with 96 CSS pixels per CSS inch, if the current pixel density is 3.125, that means that there are 96 × 3.125 = 300 device pixels per CSS inch, and thus if the image data is 300x600, it has intrinsic dimensions of 300 ÷ 3.125 = 96 CSS pixels by 600 ÷ 3.125 = 192 CSS pixels. With a current pixel density of 2.0 (192 device pixels per CSS inch) and the same image data (300x600), the intrinsic dimensions would be 150x300.

Each Document object must have a list of available images. Each image in this list is identified by a tuple consisting of an absolute URL, a CORS settings attribute mode, and, if the mode is not No CORS, an origin. Each image furthermore has an ignore higher-layer caching flag. User agents may copy entries from one Document object’s list of available images to another at any time (e.g., when the Document is created, user agents can add to it all the images that are loaded in other Documents), but must not change the keys of entries copied in this way when doing so, and must unset the ignore higher-layer caching flag for the copied entry. User agents may also remove images from such lists at any time (e.g., to save memory). User agents must remove entries in the list of available images as appropriate given higher-layer caching semantics for the resource (e.g., the HTTP Cache-Control response header) when the ignore higher-layer caching flag is unset.

The list of available images is intended to enable synchronous switching when changing the src attribute to a URL that has previously been loaded, and to avoid re-downloading images in the same document even when they don’t allow caching per HTTP. It is not used to avoid re-downloading the same image while the previous image is still loading.

For example, if a resource has the HTTP response header Cache-Control: must-revalidate, the user agent would remove it from the list of available images but could keep the image data separately, and use that if the server responds with a 204 No Content status.

Image decoding is the process which converts an encoded image’s data into a bitmap form for presentation. Implementations may choose when and what to decode for the best user experience.

Image decoding is said to be synchronous if it prevents presentation of other content until it is finished. Typically, this has an effect of atomically presenting the image and any other content at the same time. However, this presentation is delayed by the amount of time it takes to perform the decode.

Image decoding is said to be asynchronous if it does not prevent presentation of other content. This has an effect of presenting non-image content faster. However, the image content is missing on screen until the decode finishes. Once the decode is finished, the screen is updated with the image.

In both synchronous and asynchronous decoding modes, the final content is presented to screen after the same amount of time has elapsed. The main difference is whether the user agent presents non-image content ahead of presenting the final content.

In order to aid the user agent in deciding whether to perform synchronous or asynchronous decode, the decoding attribute can be set on img elements. The possible values of of the decoding attribute are the following image decoding hint keywords:

When decoding an image, the user agent should respect the preference indicated by the decoding attribute’s state. If the state indicated is auto, then the user agent is free to choose any decoding behavior.

When the user agent is to update the image data of an img element, optionally with the restart animations flag set, it must run the following steps:

1. If the element’s node document is not the active document, then run these substeps:

   1. Continue running this algorithm in parallel.
   2. Wait until the element’s node document is the active document.
   3. If another instance of this algorithm for this img element was started after this instance (even if it aborted and is no longer running), then abort these steps.
   4. Queue a microtask to continue this algorithm.
2. If the user agent cannot support images, or its support for images has been disabled, then abort the image request for the current request and the pending request, set current request to the unavailable state, let pending request be null, and abort these steps.

3. If the element does not use srcset or picture and it does not have a parent or it has a parent but it is not a picture element, and it has a src attribute specified and its value is not the empty string, let selected source be the value of the element’s src attribute, and selected pixel density be 1.0. Otherwise, let selected source be null and selected pixel density be undefined.

4. Let the img element’s last selected source be selected source.

5. If selected source is not null, run these substeps:

   1. Parse selected source, relative to the element’s node document. If that is not successful, then abort these inner set of steps. Otherwise, let urlString be the resulting URL string.
   2. Let key be a tuple consisting of urlString, the img element’s crossorigin attribute’s mode, and, if that mode is not No CORS, the node document’s origin.

   3. If the list of available images contains an entry for key, run these subsubsteps:

      1. Set the ignore higher-layer caching flag for that entry.
      2. Abort the image request for the current request and the pending request.
      3. Let pending request be null.
      4. Let current request be a new image request whose image data is that of the entry and whose state is set to the completely available state.
      5. Update the presentation of the image appropriately.
      6. Let the current request’s current pixel density be selected pixel density.
      7. Queue a task to restart the animation if restart animation is set, change current request’s current URL to urlString, and then fire a simple event named load at the img element.
      8. Abort the update the image data algorithm.
6. in parallel await a stable state, allowing the task that invoked this algorithm to continue. The synchronous section consists of all the remaining steps of this algorithm until the algorithm says the synchronous section has ended. (Steps in synchronous sections are marked with ⌛.)

7. ⌛ If another instance of this algorithm for this img element was started after this instance (even if it aborted and is no longer running), then abort these steps.

   Only the last instance takes effect, to avoid multiple requests when, for example, the src, srcset, and crossorigin attributes are all set in succession.

8. ⌛ Let selected source and selected pixel density be the URL and pixel density that results from selecting an image source, respectively.

9. ⌛ If selected source is null, run these substeps:

   1. ⌛ Set the current request to the broken state, abort the image request for the current request and the pending request, and let pending request be null.
   2. ⌛ Queue a task to change the current request’s current URL to the empty string, and then, if the element has a src attribute or it uses srcset or picture, fire a simple event named error at the img element.
   3. ⌛ Abort this algorithm.

10. ⌛ Queue a task to fire a progress event named loadstart at the img element.

    ⌛ Parse selected source, relative to the element’s node document, and let urlString be the resulting URL string. If that is not successful, run these substeps:

    1. ⌛ Abort the image request for the current request and the pending request.
    2. ⌛ Set the current request to the broken state.
    3. ⌛ Let pending request be null.
    4. ⌛ Queue a task to change the current request’s current URL to selected source, fire a simple event named error at the img element and then fire a simple event named loadend at the img element.
    5. ⌛ Abort the update the image data algorithm.

11. ⌛ If the pending request is not null, and urlString is the same as the pending request’s current URL, then abort these steps.

    ⌛ If urlString is the same as the current request’s current URL, and current request is in the partially available state, then abort the image request for the pending request, queue a task to restart the animation if restart animation is set, and abort these steps.

    ⌛ If the pending request is not null, abort the image request for the pending request.

    ⌛ Let image request be a new image request whose current URL is urlString.

    ⌛ If current request is in the unavailable state or the broken state, let the current request be image request. Otherwise, let the pending request be image request.

    ⌛ Let request be the result of creating a potential-CORS request given urlString and the current state of the element’s crossorigin content attribute.

    ⌛ Set request’s client to the element’s node document’s Window object’s environment settings object and type to "image".

    ⌛ If the element uses srcset or picture, set request’s initiator to "imageset".

    ⌛ Set request’s referrer policy to the current state of the element’s referrerpolicy attribute.

    ⌛ Fetch request. Let this instance of the fetching algorithm be associated with image request.

    The resource obtained in this fashion, if any, is image request’s image data. It can be either CORS-same-origin or CORS-cross-origin; this affects the origin of the image itself (e.g., when used on a canvas).

    Fetching the image must delay the load event of the element’s node document until the task that is queued by the networking task source once the resource has been fetched (defined below) has been run.

    This, unfortunately, can be used to perform a rudimentary port scan of the user’s local network (especially in conjunction with scripting, though scripting isn’t actually necessary to carry out such an attack). User agents may implement cross-origin access control policies that are stricter than those described above to mitigate this attack, but unfortunately such policies are typically not compatible with existing Web content.

    If the resource is CORS-same-origin, each task that is queued by the networking task source while the image is being fetched, if image request is the current request, must fire a progress event named progress at the img element.

12. End the synchronous section, continuing the remaining steps in parallel, but without missing any data from fetching.

13. As soon as possible, jump to the first applicable entry from the following list:

    If the resource type is multipart/x-mixed-replace

    The next task that is queued by the networking task source while the image is being fetched must run the following steps:

    1. If image request is the pending request and at least one body part has been completely decoded, abort the image request for the current request, upgrade the pending request to the current request.

    2. Otherwise, if image request is the pending request and the user agent is able to determine that image request’s image is corrupted in some fatal way such that the image dimensions cannot be obtained, abort the image request for the current request, upgrade the pending request to the current request and set the current request’s state to broken.

    3. Otherwise, if image request is the current request, it is in the unavailable state, and the user agent is able to determine image request’s image’s width and height, set the current request’s state to partially available.

    4. Otherwise, if image request is the current request, it is in the unavailable state, and the user agent is able to determine that image request’s image is corrupted in some fatal way such that the image dimensions cannot be obtained, set the current request’s state to broken.

    Each task that is queued by the networking task source while the image is being fetched must update the presentation of the image, but as each new body part comes in, it must replace the previous image. Once one body part has been completely decoded, the user agent must set the img element to the completely available state and queue a task to fire a simple event named load at the img element.

    The progress and loadend events are not fired for multipart/x-mixed-replace image streams.

    If the resource type and data corresponds to a supported image format, as described below

    The next task that is queued by the networking task source while the image is being fetched must run the following steps:

    1. If the user agent is able to determine image request’s image’s width and height, and image request is pending request, set image request’s state to partially available.

    2. Otherwise, if the user agent is able to determine image request’s image’s width and height, and image request is current request, update the img element’s presentation appropriately and set image request’s state to partially available.

    3. Otherwise, if the user agent is able to determine that image request’s image is corrupted in some fatal way such that the image dimensions cannot be obtained, and image request is pending request, abort the image request for the current request and the pending request, upgrade the pending request to the current request, set current request to the broken state, fire a simple event named error at the img element, fire a simple event named loadend at the img element, and abort these steps.

    4. Otherwise, if the user agent is able to determine that image request’s image is corrupted in some fatal way such that the image dimensions cannot be obtained, and image request is current request, abort the image request for image request, fire a simple event named error at the img element, fire a simple event named loadend at the img element, and abort these steps.

    That task, and each subsequent task, that is queued by the networking task source while the image is being fetched, if image request is the current request, must update the presentation of the image appropriately (e.g., if the image is a progressive JPEG, each packet can improve the resolution of the image).

    Furthermore, the last task that is queued by the networking task source once the resource has been fetched must additionally run these steps:

    1. If image request is the pending request, abort the image request for the current request, upgrade the pending request to the current request and update the img element’s presentation appropriately.
    2. Set image request to the completely available state.
    3. Add the image to the list of available images using the key key, with the ignore higher-layer caching flag set.
    4. Fire a progress event or simple event named load at the img element, depending on the resource in image request.
    5. Fire a progress event or simple event named loadend at the img element, depending on the resource in image request.

    Otherwise

    The image data is not in a supported file format; the user agent must set image request to the broken state, abort the image request for the current request and the pending request, upgrade the pending request to the current request if image request is the pending request, and then queue a task to first fire a simple event named error at the img element and then fire a simple event named loadend at the img element.

To abort the image request for an image request image request means to run the following steps:

1. Forget image request’s image data, if any.
2. Abort any instance of the fetching algorithm for image request, discarding any pending tasks generated by that algorithm.

To upgrade the pending request to the current request for an img element means to run the following steps:

1. Let the img element’s current request be the pending request.
2. Let the img element’s pending request be null.

To fire a progress event or simple event named type at an element e, depending on resource r, means to fire a progress event named type at e if r is CORS-same-origin, and otherwise fire a simple event named type at e.

While a user agent is running the above algorithm for an element x, there must be a strong reference from the element’s node document to the element x, even if that element is not in its Document.

An img element is said to use srcset or picture if it has a srcset attribute specified or if it has a parent that is a picture element.

When an img element is in the completely available state and the user agent can decode the media data without errors, then the img element is said to be fully decodable.

Whether the image is fetched successfully or not (e.g., whether the response status was an ok status) must be ignored when determining the image’s type and whether it is a valid image.

This allows servers to return images with error responses, and have them displayed.

The user agent should apply the image sniffing rules to determine the type of the image, with the image’s associated Content-Type headers giving the official type. If these rules are not applied, then the type of the image must be the type given by the image’s associated Content-Type headers.

User agents must not support non-image resources with the img element (e.g., XML files whose document element is an HTML element). User agents must not run executable code (e.g., scripts) embedded in the image resource. User agents must only display the first page of a multipage resource (e.g., a PDF file). User agents must not allow the resource to act in an interactive fashion, but should honor any animation in the resource.

This specification does not specify which image types are to be supported.

An img element is associated with a source set.

A source set is an ordered set of zero or more image sources and a source size.

An image source is a URL, and optionally either a density descriptor, or a width descriptor.

A source size is a <source-size-value>. When a source size has a unit relative to the viewport, it must be interpreted relative to the img element’s document’s viewport. Other units must be interpreted the same as in Media Queries. [MEDIAQ]

When asked to select an image source for a given img element el, user agents must do the following:

1. Update the source set for el.
2. If el’s source set is empty, return null as the URL and undefined as the pixel density and abort these steps.
3. Otherwise, take el’s source set and let it be source set.
4. If an entry b in source set has the same associated density descriptor as an earlier entry a in source set, then remove entry b. Repeat this step until none of the entries in source set have the same associated density descriptor as an earlier entry.
5. In a user agent-specific manner, choose one image source from source set. Let this be selected source.
6. Return selected source and its associated pixel density.

When asked to update the source set for a given img element el, user agents must do the following:

1. Set el’s source set to an empty source set.
2. If el has a parent node and that is a picture element, let elements be an array containing el’s parent node’s child elements, retaining relative order. Otherwise, let elements be array containing only el.
3. If el has a width attribute, and parsing that attribute’s value using the rules for parsing dimension values doesn’t generate an error or a percentage value, then let width be the returned integer value. Otherwise, let width be null.

4. Iterate through elements, doing the following for each item child:

   1. If child is el:

      1. If child has a srcset attribute, parse child’s srcset attribute and let the returned source set be source set. Otherwise, let source set be an empty source set.
      2. Parse child’s sizes attribute with the fallback width width, and let source set’s source size be the returned value.
      3. If child has a src attribute whose value is not the empty string and source set does not contain an image source with a density descriptor value of 1, and no image source with a width descriptor, append child’s src attribute value to source set.
      4. Normalize the source densities of source set.
      5. Let el’s source set be source set.
      6. Abort this algorithm.
   2. If child is not a source element, continue to the next child. Otherwise, child is a source element.
   3. If child does not have a srcset attribute, continue to the next child.
   4. Parse child’s srcset attribute and let the returned source set be source set.
   5. If source set has zero image sources, continue to the next child.
   6. If child has a media attribute, and its value does not match the environment, continue to the next child.
   7. Parse child’s sizes attribute with the fallback width width, and let source set’s source size be the returned value.
   8. If child has a type attribute, and its value is an unknown or unsupported MIME type, continue to the next child.
   9. Normalize the source densities of source set.
   10. Let el’s source set be source set.
   11. Abort this algorithm.

Each img element independently considers its previous sibling source elements plus the img element itself for selecting an image source, ignoring any other (invalid) elements, including other img elements in the same picture element, or source elements that are following siblings of the relevant img element.

When asked to parse a srcset attribute from an element, parse the value of the element’s srcset attribute as follows:

1. Let input be the value passed to this algorithm.
2. Let position be a pointer into input, initially pointing at the start of the string.
3. Let candidates be an initially empty source set.
4. Splitting loop: Collect a sequence of characters that are space characters or U+002C COMMA characters. If any U+002C COMMA characters were collected, that is a parse error.
5. If position is past the end of input, return candidates and abort these steps.
6. Collect a sequence of characters that are not space characters, and let that be url.
7. Let descriptors be a new empty list.

8. If url ends with a U+002C COMMA character (,), follow these substeps:

   1. Remove all trailing U+002C COMMA characters from url. If this removed more than one character, that is a parse error.

   Otherwise, follow these substeps:

   1. Descriptor tokenizer: Skip white space
   2. Let current descriptor be the empty string.
   3. Let state be in descriptor.

   4. Let c be the character at position. Do the following depending on the value of state. For the purpose of this step, "EOF" is a special character representing that position is past the end of input.

      In descriptor

      Do the following, depending on the value of c:

      Space character

      If current descriptor is not empty, append current descriptor to descriptors and let current descriptor be the empty string. Set state to after descriptor.

      U+002C COMMA (,)

      Advance position to the next character in input. If current descriptor is not empty, append current descriptor to descriptors. Jump to the step labeled descriptor parser.

      U+0028 LEFT PARENTHESIS (()

      Append c to current descriptor. Set state to in parens.

      EOF

      If current descriptor is not empty, append current descriptor to descriptors. Jump to the step labeled descriptor parser.

      Anything else

      Append c to current descriptor.

      In parens

      Do the following, depending on the value of c:

      U+0029 RIGHT PARENTHESIS ())

      Append c to current descriptor. Set state to in descriptor.

      EOF

      Append current descriptor to descriptors. Jump to the step labeled descriptor parser.

      Anything else

      Append c to current descriptor.

      After descriptor

      Do the following, depending on the value of c:

      Space character

      Stay in this state.

      EOF

      Jump to the step labeled descriptor parser.

      Anything else

      Set state to in descriptor. Set position to the previous character in input.

      Advance position to the next character in input. Repeat this substep.

      In order to be compatible with future additions, this algorithm supports multiple descriptors and descriptors with parens.

9. Descriptor parser: Let error be no.
10. Let width be absent.
11. Let density be absent.
12. Let future-compat-h be absent.

13. For each descriptor in descriptors, run the appropriate set of steps from the following list:

    If the descriptor consists of a valid non-negative integer followed by a U+0077 LATIN SMALL LETTER W character

    1. If the user agent does not support the sizes attribute, let error be yes.

       A conforming user agent will support the sizes attribute. However, user agents typically implement and ship features in an incremental manner in practice.

    2. If width and density are not both absent, then let error be yes.
    3. Apply the rules for parsing non-negative integers to the descriptor. If the result is zero, let error be yes. Otherwise, let width be the result.

    If the descriptor consists of a valid floating-point number followed by a U+0078 LATIN SMALL LETTER X character

    1. If width, density and future-compat-h are not all absent, then let error be yes.

    2. Apply the rules for parsing floating-point number values to the descriptor. If the result is less than zero, let error be yes. Otherwise, let density be the result.

       If density is zero, the intrinsic dimensions will be infinite. User agents are expected to have limits in how big images can be rendered, which is allowed by the hardware limitations clause.

    If the descriptor consists of a valid non-negative integer followed by a U+0068 LATIN SMALL LETTER H character

    This is a parse error.

    1. If future-compat-h and density are not both absent, then let error be yes.
    2. Apply the rules for parsing non-negative integers to the descriptor. If the result is zero, let error be yes. Otherwise, let future-compat-h be the result.

    Anything else

    Let error be yes.

14. If future-compat-h is not absent and width is absent, let error be yes.
15. If error is still no, then append a new image source to candidates whose URL is url, associated with a width width if not absent and a pixel density density if not absent. Otherwise, there is a parse error.
16. Return to the step labeled splitting loop.

When asked to parse a sizes attribute from an element, parse a comma-separated list of component values from the value of the element’s sizes attribute (or the empty string, if the attribute is absent), and let unparsed sizes list be the result. [CSS-SYNTAX-3]

For each unparsed size in unparsed sizes list:

1. Remove all consecutive <whitespace-token>s from the end of unparsed size. If unparsed size is now empty, that is a parse error; continue to the next iteration of this algorithm.
2. If the last component value in unparsed size is a valid non-negative <source-size-value>, let size be its value and remove the component value from unparsed size. Any CSS function other than the calc() function is invalid. Otherwise, there is a parse error; continue to the next iteration of this algorithm.
3. Remove all consecutive <whitespace-token>s from the end of unparsed size. If unparsed size is now empty, return size and exit this algorithm. If this was not the last item in unparsed sizes list, that is a parse error.
4. Parse the remaining component values in unparsed size as a <media-condition>. If it does not parse correctly, or it does parse correctly but the <media-condition> evaluates to false, continue to the next iteration of this algorithm. [MEDIAQ]
5. Return size and exit this algorithm.

If the above algorithm exhausts unparsed sizes list without returning a size value, follow these steps:

1. If width is not null, return a <length> with the value width and the unit px.
2. Return 100vw.

A parse error for the algorithms above indicates a non-fatal mismatch between input and requirements. User agents are encouraged to expose parse errors somehow.

While a valid source size list only contains a bare <source-size-value> (without an accompanying <media-condition>) as the last entry in the <source-size-list>, the parsing algorithm technically allows such at any point in the list, and will accept it immediately as the size if the preceding entries in the list weren’t used. This is to enable future extensions, and protect against simple author errors such as a final trailing comma.

An image source can have a density descriptor, a width descriptor, or no descriptor at all accompanying its URL. Normalizing a source set gives every image source a density descriptor.

When asked to normalize the source densities of a source set source set, the user agent must do the following:

1. Let source size be source set’s source size.

2. For each image source in source set:

   1. If the image source has a density descriptor, continue to the next image source.

   2. Otherwise, if the image source has a width descriptor, replace the width descriptor with a density descriptor with a value of the width descriptor divided by the source size and a unit of x.

      If the source size is zero, the density would be infinity, which results in the intrinsic dimensions being zero by zero.

   3. Otherwise, give the image source a density descriptor of 1x.

The user agent may at any time run the following algorithm to update an img element’s image in order to react to changes in the environment. (User agents are not required to ever run this algorithm; for example, if the user is not looking at the page any more, the user agent might want to wait until the user has returned to the page before determining which image to use, in case the environment changes again in the meantime.)

User agents are encouraged to run this algorithm in particular when the user changes the viewport’s size (e.g., by resizing the window or changing the page zoom), and when an img element is inserted into a document, so that the density-corrected intrinsic width and height match the new viewport, and so that the correct image is chosen when art direction is involved.

1. in parallel await a stable state. The synchronous section consists of all the remaining steps of this algorithm until the algorithm says the synchronous section has ended. (Steps in synchronous sections are marked with ⌛.)
2. ⌛ If the img element does not use srcset or picture, its node document is not the active document, has image data whose resource type is multipart/x-mixed-replace, or the pending request is not null, then abort this algorithm.
3. ⌛ Let selected source and selected pixel density be the URL and pixel density that results from selecting an image source, respectively.
4. ⌛ If selected source is null, then abort these steps.
5. ⌛ If selected source and selected pixel density are the same as the element’s last selected source and current pixel density, then abort these steps.
6. ⌛ Parse selected source, relative to the element’s node document, and let urlString be the resulting URL string. If that is not successful, abort these steps.
7. ⌛ Let corsAttributeState be the state of the element’s crossorigin content attribute.
8. ⌛ Let origin be the origin of the img element’s node document.
9. ⌛ Let client be the img element’s node document’s Window object’s environment settings object.
10. ⌛ Let key be a tuple consisting of urlString, corsAttributeState, and, if corsAttributeState is not No CORS, origin.
11. ⌛ Let image request be a new image request whose current URL is urlString
12. ⌛ Let the element’s pending request be image request.
13. End the synchronous section, continuing the remaining steps in parallel.

14. If the list of available images contains an entry for key, then set image request’s image data to that of the entry. Continue to the next step.

    Otherwise, run these substeps:

    1. Let request be the result of creating a potential-CORS request given urlString and corsAttributeState.
    2. Set request’s client to client, type to "image", and set request’s synchronous flag.
    3. Set request’s referrer policy to the current state of the element’s referrerpolicy attribute.
    4. Let response be the result of fetching request.
    5. If response’s unsafe response is a network error or if the image format is unsupported (as determined by applying the image sniffing rules, again as mentioned earlier), or if the user agent is able to determine that image request’s image is corrupted in some fatal way such that the image dimensions cannot be obtained, or if the resource type is multipart/x-mixed-replace, then let pending request be null and abort these steps.
    6. Otherwise, response’s unsafe response is image request’s image data. It can be either CORS-same-origin or CORS-cross-origin; this affects the origin of the image itself (e.g., when used on a canvas).

15. Queue a task to run the following substeps:

    1. If the img element has experienced relevant mutations since this algorithm started, then let pending request be null and abort these steps.
    2. Let the img element’s last selected source be selected source and the img element’s current pixel density be selected pixel density.
    3. Set image request to the completely available state.
    4. Add the image to the list of available images using the key key, with the ignore higher-layer caching flag set.
    5. Upgrade the pending request to the current request.
    6. Update the img element’s presentation appropriately.
    7. Fire a simple event named load at the img element.

The task source for the tasks queued by algorithms in this section is the DOM manipulation task source.

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 (e.g. alt="" or alt without a set value)

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

There is no textual equivalent of the image available.

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

1. 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 Text node descendants other than inter-element white space, and no embedded content descendant other than the img element, then the contents of the first such figcaption element are the caption information; abort these steps.
2. 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.

In the case where an img without an alt attribute is the child of a figure element with a non-empty figcaption element, the image’s presence should be minimally conveyed to a user by Assistive Technology, typically by identifying the image role.

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.

Users who do not have a pointing device, or who cannot see the image referred to will generally not be able to use a server-side image map successfully. Authors should use another mechanism, such as a "client-side" image map made using the usemap attribute, wherever possible.

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.

<figure>
  <a href="solve.html">
    <img src="zoo.jpg" ismap alt="Animals and people at the zoo, among them Wally with striped clothes">
  </a>
  <figcaption>Where’s Wally? Click on him!</figcaption>
</figure>

The definition of the a element explains how the coordinates of the click event on an img element with ismap attribute inside an a element are communicated to the server.

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.

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

The crossOrigin IDL attribute must reflect the crossorigin content attribute.

The useMap IDL attribute must reflect the usemap content attribute.

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.

The longDesc IDL attribute is defined in [html-longdesc]. The IDL attribute must reflect the longdesc content attribute.

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

Returns the image decoding hint set for this image.

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.

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

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

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

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

• Both the src attribute and the srcset attribute are omitted.
• The srcset attribute is omitted and the src attribute’s value is the empty string.
• The final task that is queued by the networking task source once the resource has been fetched has been queued.
• The img element is completely available.
• The img element is broken.

Otherwise, the attribute must return false.

The value of complete can thus change while a script is executing.

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

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

1. If any of the following conditions are true about this img element:
   • its node document is not an active document;
   • its current request's state is broken,

   then reject promise with an "EncodingError" DOMException.

2. Otherwise, in parallel, wait for one of the following cases to occur, and perform the corresponding actions:

   This img element’s node document stops being an active document

   This img element’s current request changes or is mutated

   This img element’s current request's state becomes broken

   Reject promise with an "EncodingError" DOMException.

   This img element’s current request's state becomes completely available

   Decode the image.

   If decoding does not need to be performed for this image, resolve promise with undefined. An example of this case would be for vector graphics.

   If decoding fails, reject promise with an "EncodingError" DOMException. An example of this would be corrupt image data or attempting to decode an image encoded by an unsupported codec.

   If the decoding process completes successfully, resolve promise with undefined.

   User agents should ensure that the decoded media image is readily available until at least the end of the next successful update the rendering step in the event loop.

   Implementations may choose to discard the decoded image data in the event it is difficult to keep the decoded copy ready. Low memory situations or large images would be cases where implementations may choose to do this.

   Implementations are expected to treat animated images that have all frames loaded as completely available.

3. Return promise.

A constructor is provided for creating HTMLImageElement objects (in addition to the factory methods from DOM such as createElement()): Image(width, height). When invoked as a constructor, this must return a new HTMLImageElement object (a new img element). If the width argument is present, the new object’s width content attribute must be set to width. If the height argument is also present, the new object’s height content attribute must be set to height. The element’s node document must be the active document of the browsing context of the Window object on which the interface object of the invoked constructor is found.

4.7.5.1. Requirements for providing text to act as an alternative for images

Text alternatives, [WCAG20] are a primary way of making visual information accessible, because they can be rendered through many sensory modalities (for example, visual, auditory or tactile) to match the needs of the user. Providing text alternatives allows the information to be rendered in a variety of ways by a variety of user agents. For example, a person who cannot see a picture can hear the text alternative read aloud using synthesized speech.

4.7.5.1.1. Examples of scenarios where users benefit from text alternatives for images

• They have a very slow connection and are browsing with images disabled.
• They have a vision impairment and use text to speech software.
• They have a cognitive impairment and use text to speech software.
• They are using a text-only browser.
• They are listening to the page being read out by a voice Web browser.
• They have images disabled to save on download costs.
• They have problems loading images or the source of an image is wrong.

4.7.5.1.2. General guidelines

Except where otherwise specified, the alt attribute must be specified and its value must not be empty; the value must be an appropriate functional replacement for the image. The specific requirements for the alt attribute content depend on the image’s function in the page, as described in the following sections.

To determine an appropriate text alternative it is important to think about why an image is being included in a page. What is its purpose? Thinking like this will help you to understand what is important about the image for the intended audience. Every image has a reason for being on a page, because it provides useful information, performs a function, labels an interactive element, enhances aesthetics or is purely decorative. Therefore, knowing what the image is for, makes writing an appropriate text alternative easier.

4.7.5.1.3. A link or button containing nothing but an image

When an a element that is a hyperlink, or a button element, has no text content but contains one or more images, include text in the alt attribute(s) that together convey the purpose of the link or button.

<ul>
  <li><button><img src="b.png" alt="Bold"></button></li>
  <li><button><img src="i.png" alt="Italics"></button></li>
  <li><button><img src="strike.png" alt="Strike through"></button></li>
  <li><button><img src="blist.png" alt="Bulleted list"></button></li>
  <li><button><img src="nlist.png" alt="Numbered list"></button></li>
</ul>

<a href="https://w3.org">
  <img src="images/w3c_home.png" width="72" height="48" alt="W3C web site">
</a>

<a href="https://w3.org">
  <img src="images/w3c_home.png" width="72" height="48" alt="W3C home">
</a>

<a href="preview.html">
  <img src="images/preview.png" width="32" height="30" alt="Print preview.">
</a>

<button>
  <img src="images/search.png" width="74" height="29" alt="Search">
</button>

<a href="pipco-home.html">
  <img src="pip.gif" alt="PIP CO home"><img src="co.gif" alt="">
</a>

4.7.5.1.4. Graphical Representations: Charts, diagrams, graphs, maps, illustrations

Users can benefit when content is presented in graphical form, for example as a flowchart, a diagram, a graph, or a map showing directions. Users who are unable to view the image also benefit when content presented in a graphical form is provided in a text-based format. Software agents that process text content, but cannot automatically process images (e.g. translation services, many search engines), also benefit from a text-based description.

<img src="piechart.gif" alt="Pie chart: Browser Share - Internet Explorer 25%, Firefox 40%, Chrome 25%, Safari 6% and Opera 4%.">

<p id="graph7">According to a recent study Firefox has a 40% browser share,
  Internet Explorer has 25%, Chrome has 25%, Safari has 6% and Opera has 4%.</p>
<p><img src="piechart.gif" alt="The browser shares as a pie chart."
  longdesc="#graph7"></p>

In cases where the text alternative is lengthy, more than a sentence or two, or would benefit from the use of structured markup, provide a brief description or label using the alt attribute, and an associated text alternative.

<a href="#desc"><img src="flowchart.gif"
  alt="Flowchart: Dealing with a broken lamp." longdesc="#desc"></a>

...

...

<div id="desc">
  <h2>Dealing with a broken lamp</h2>
  <ol>
    <li>Check if it’s plugged in, if not, plug it in.</li>
    <li>If it still doesn’t work; check if the bulb is burned out. If it is, replace the bulb.</li>
    <li>If it still doesn’t work; buy a new lamp.</li>
  </ol>
</div>

<figure>
  <figcaption>Rainfall Data</figcaption>
  <img src="rainchart.gif" alt="Bar chart: average rainfall by Country and Season.
    Full description in Table below." longdesc="#table-4">
  <table id="table-4">
    <caption>Rainfall in millimetres by Country and Season.</caption>
    <tr>
      <td>
      <th scope="col">UK
      <th scope="col">Japan
      <th scope="col">Australia
    </tr>
    <tr>
      <th scope="row">Spring
      <td>5.5 (highest)
      <td>2.4
      <td>2 (lowest)
    </tr>
    <tr>
      <th scope="row">Summer
      <td>4.5 (highest)
      <td>3.4
      <td>2 (lowest)
    </tr>
    <tr>
      <th scope="row">Autumn
      <td>3.5 (highest)
      <td>1.8
      <td>1.5 (lowest)
    </tr>
    <tr>
      <th scope="row">Winter
      <td>1.5 (highest)
      <td>1.2
      <td>1 lowest
    </tr>
  </table>
</figure>

For any of the examples in this section the details and summary elements could be used so that the text descriptions for the images are only displayed on demand:

<figure>
  <img src="flowchart.gif" alt="Flowchart: Dealing with a broken lamp.">
  <details>
    <summary>Dealing with a broken lamp</summary>
    <ol>
      <li>Check if it’s plugged in, if not, plug it in.</li>
      <li>If it still doesn’t work; check if the bulb is burned out. If it is, replace the bulb.</li>
      <li>If it still doesn’t work; buy a new lamp.</li>
    </ol>
  </details>
</figure>

4.7.5.1.5. Images of text

Sometimes, an image only contains text, and the purpose of the image is to display text using visual effects and /or fonts. It is strongly recommended that text styled using CSS be used, but if this is not possible, provide the same text in the alt attribute as is in the image.

<h1><img src="gethappy.gif" alt="Get Happy!"></h1>

<p><img src="sale.gif" alt="The BIG sale ...ends Friday."></p>

<p>Only <img src="euro.png" alt="euro ">5.99!

An image should not be used if Unicode characters would serve an identical purpose. Only when the text cannot be directly represented using Unicode, e.g., because of decorations or because the character is not in the Unicode character set (as in the case of gaiji), would an image be appropriate.

If an author is tempted to use an image because their default system font does not support a given character, then Web Fonts are a better solution than images.

An illuminated manuscript might use graphics for some of its letters. The text alternative in such a situation is just the character that the image represents. nce upon a time and a long long time ago...

<p><img src="initials/fancyO.png" alt="O">nce upon a time and a long long time ago...

Where the design of the illuminated letter is important, the primary text alternative in is the character that the image represents, and longdesc can provide a link to a more detailed description: nce upon a time and a long long time ago...

<p><img src="initials/story-o.jpg" alt="O" longdesc="letters/story-0.html">nce
  upon a time and a long long time ago...

4.7.5.1.6. Images that include text

Sometimes, an image consists of a graphics such as a chart and associated text. In this case it is recommended that the text in the image is included in the text alternative.

<p><img src="figure1.gif" alt="Figure 1. Distribution of Articles by Journal Category.
Pie chart: Language=68%, Education=14% and Science=18%."></p>

<figure>
  <img src="figure1.gif" alt="Figure 1">
  <figcaption>
    <strong>Figure 1.</strong> Distribution of Articles by Journal Category. Pie chart: Language=68%, Education=14% and Science=18%.
  </figcaption>
</figure>

4.7.5.1.7. Images that enhance the themes or subject matter of the page content

An image that isn’t discussed directly by the surrounding text but still has some relevance can be included in a page using the img element. Such images are more than mere decoration, they may augment the themes or subject matter of the page content and so still form part of the content. In these cases, it is recommended that a text alternative be provided.

<header>
<h1>The Lady of Shalott</h1>
<p>A poem by Alfred Lord Tennyson</p>
</header>

<img src="shalott.jpg" alt="Painting - a young woman with long hair, sitting in a wooden boat. Full description below." longdesc="#des">
<p><a href="#des">Description of the painting</a>.</p>

<!-- Full Recitation of Alfred, Lord Tennyson’s Poem.  -->

...
...
...
<p id="des">The woman in the painting is wearing a flowing white dress. A large piece of intricately patterned fabric is draped over the side. In her right hand she holds the chain mooring the boat. Her expression is mournful. She stares at a crucifix lying in front of her. Beside it are three candles. Two have blown out.
<a href="https://www.tate.org.uk/art/artworks/waterhouse-the-lady-of-shalott-n01543">Further information about the painting</a>.</p>

<img src="orateur_robin_berjon.png" alt="Portrait photo (black and white) of Robin.">
<h1>Robin Berjon</h1>
<p>What more needs to be said?</p>

<header>
  <h1>The Lady of Shalott</h1>
  <p>A poem by Alfred Lord Tennyson</p>
</header>
<figure>
  <img src="shalott.jpeg" alt="Painting: a woman in a white flowing dress, sitting in a small boat.">
  <p><a href="http://www.tate.org.uk/art/artworks/waterhouse-the-lady-of-shalott-n01543">About this painting: The Lady of Shalott.</a></p>
</figure>
<!-- Full Recitation of Alfred, Lord Tennyson’s Poem.  -->

4.7.5.1.8. A graphical representation of some of the surrounding text

In many cases, the image is actually just supplementary, and its presence merely reinforces the surrounding text. In these cases, the alt attribute must be present but its value must be unset or the empty string.

In general, an image falls into this category if removing the image doesn’t make the page any less useful, but including the image makes it a lot easier for users of visual browsers to understand the concept.

<p>
  In the text file, add <code>SleepMode=1</code> under <code>[options]</code>, then save and close.
</p>
<img src="images/text.png" alt="">

4.7.5.1.9. A purely decorative image that doesn’t add any information

Purely decorative images are visual enhancements, decorations or embellishments that provide no function or information beyond aesthetics to users who can view the images.

Mark up purely decorative images so they can be ignored by assistive technology by using an alt attribute with no value (e.g. alt="" or alt with no set value). While it is not unacceptable to include decorative images inline, it is recommended if they are purely decorative to include the image using CSS.

<header>
  <div><img src="border.gif" alt width="400" height="30"></div>
  <h1>Clara’s Blog</h1>
</header>
<p>Welcome to my blog...</p>

4.7.5.1.10. Inline images

When images are used inline as part of the flow of text in a sentence, provide a word or phrase as a text alternative which makes sense in the context of the sentence it is a part of.

I you.

I <img src="heart.png" alt="love"> you.

My breaks.

My <img src="heart.png" alt="heart"> breaks.

4.7.5.1.11. A group of images that form a single larger picture with no links

When a picture has been sliced into smaller image files that are then displayed together to form the complete picture again, include a text alternative for one of the images using the alt attribute as per the relevant guidance for the picture as a whole, and then include an empty alt attribute on the other images.

<img src="pip.gif" alt="PIP CO"><img src="co.gif" alt="">

In the following example, a rating is shown as three filled stars and two empty stars. While the text alternative could have been "★★★☆☆", the author has instead decided to more helpfully give the rating in the form "3 out of 5". That is the text alternative of the first image, and the rest have empty alt attributes.

<p>Rating:
  <img src="1" alt="3 out of 5">
  <img src="1" alt=""><img src="1" alt="">
  <img src="0" alt=""><img src="0" alt="">
</p>

4.7.5.1.12. Image maps

<p>View houses for sale in North Katoomba or South Katoomba:</p>
  <p><img src="imagemap.png" width="209" alt="Map of Katoomba" height="249" usemap="#Map">

  <map name="Map">
  <area shape="poly" coords="78,124,124,10,189,29,173,93,168,132,136,151,110,130"
  href="north.html" alt="Houses in North Katoomba">
  <area shape="poly" coords="66,63,80,135,106,138,137,154,167,137,175,133,144,240,49,223,17,137,17,61"
  alt="Houses in South Katoomba" href="south.html">
  </map>

4.7.5.1.13. A group of images that form a single larger picture with links

Sometimes, when you create a composite picture from multiple images, you may wish to link one or more of the images. Provide an alt attribute for each linked image to describe the purpose of the link.

<h1>The crocoduck</h1>
<p>You encounter a strange creature called a "crocoduck".
The creature seems angry! Perhaps some friendly stroking will help to calm
it, but be careful not to stroke any crocodile parts. This would just enrage
the beast further.</p>
<a href="?stroke=head"><img src="crocoduck1.png" alt="Stroke crocodile’s angry, chomping head"></a>
<a href="?stroke=body"><img src="crocoduck2.png" alt="Stroke duck’s soft, feathery body"></a>

4.7.5.1.14. Images of Pictures

Images of pictures or graphics include visual representations of objects, people, scenes, abstractions, etc. This non-text content, [WCAG20] can convey a significant amount of information visually or provide a specific sensory experience, [WCAG20] to a sighted person. Examples include photographs, paintings, drawings and artwork.

An appropriate text alternative for a picture is a brief description, or name [WCAG20]. As in all text alternative authoring decisions, writing suitable text alternatives for pictures requires human judgment. The text value is subjective to the context where the image is used and the page author’s writing style. Therefore, there is no single "right" or "correct" piece of alt text for any particular image. In addition to providing a short text alternative that gives a brief description of the non-text content, also providing supplemental content through another means when appropriate may be useful.

<figure>
  <img src="664aef.jpg" alt="Lola the cat sitting under an umbrella in the bath tub.">
  <figcaption>Lola prefers a bath to a shower.</figcaption>
</figure>

<figure>
  <img src="Rorschach1.jpg" alt="An abstract, freeform, vertically symmetrical, black inkblot on a light background.">
  <figcaption>The first of the ten cards in the Rorschach test.</figcaption>
</figure>

4.7.5.1.15. Webcam images

Webcam images are static images that are automatically updated periodically. Typically the images are from a fixed viewpoint, the images may update on the page automatically as each new image is uploaded from the camera or the user may be required to refresh the page to view an updated image. Examples include traffic and weather cameras.

<figure>
  <img src="webcam1.jpg" alt="Sopwith house weather cam. Taken on the 21/04/10 at 11:51 and 34 seconds. In the foreground are the safety rails on the flat part of the roof. Nearby there are low rize industrial buildings, beyond are blocks of flats. In the distance there’s a church steeple.">
  <figcaption>View from Sopwith house, looking towards north Kingston. This image is updated every hour.</figcaption>
</figure>
<p>View the <a href="https://www.bbc.co.uk/weather/0/6690829">latest weather details</a> for Kingston upon Thames.</p>

4.7.5.1.16. When a text alternative is not available at the time of publication

In some cases an image is included in a published document, but the author is unable to provide an appropriate text alternative. In such cases the minimum requirement is to provide a caption for the image using the figure and figcaption elements under the following conditions:

• The img element is in a figure element
• The figure element contains a figcaption element
• The figcaption element contains content other than inter-element white space
• Ignoring the figcaption element and its descendants, the figure element has no Text node descendants other than inter-element white space, and no embedded content descendant other than the img element.

In other words, the only content of the figure is an img element and a figcaption element, and the figcaption element must include (caption) content.

Such cases are to be kept to an absolute minimum. If there is even the slightest possibility of the author having the ability to provide real alternative text, then it would not be acceptable to omit the alt attribute.

In this example, a person uploads a photo, as part of a bulk upload of many images, to a photo sharing site. The user has not provided a text alternative or a caption for the image. The site’s authoring tool inserts a caption automatically using whatever useful information it has for the image. In this case it’s the file name and date the photo was taken.

The caption text in the example below is not a suitable text alternative and is not conforming to the Web Accessibility Guidelines 2.0. [WCAG20]

<figure>
  <img src="clara.jpg">
  <figcaption>clara.jpg, taken on 12/11/2010.</figcaption>
</figure>

Notice that even in this example, as much useful information as possible is still included in the figcaption element.

In this second example, a person uploads a photo to a photo sharing site. She has provided a caption for the image but not a text alternative. This may be because the site does not provide users with the ability to add a text alternative in the alt attribute.

<figure>
  <img src="elo.jpg">
  <figcaption>Eloisa with Princess Belle</figcaption>
</figure>

<table>
  <tr>
    <th>Image</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>
      <figure>
        <img src="2421.png">
        <figcaption>Image 640 by 100, filename 'banner.gif'</figcaption>
      </figure>
    </td>
    <td>
      <input name="alt2421">
    </td>
  </tr>
  <tr>
    <td>
      <figure>
        <img src="2422.png">
        <figcaption>Image 200 by 480, filename 'ad3.gif'</figcaption>
      </figure>
    </td>
    <td>
      <input name="alt2422">
    </td>
  </tr>
</table>

Since some users cannot use images at all (e.g., because they are blind) the alt attribute is only allowed to be omitted when no text alternative is available and none can be made available, as in the above examples.

4.7.5.1.17. An image not intended for the user

Generally authors should avoid using img elements for purposes other than showing images.

If an img element is being used for purposes other than showing an image, e.g., as part of a service to count page views, use an empty alt attribute.

<img src="https://stats.example.com/count?site=w3.org" width="0" height="0" alt="">

It is recommended for the example use above the width and height attributes be set to zero.

<img src="spacer.gif" width="10" height="10" alt="">

It is recommended that CSS be used to position content instead of img elements.

4.7.5.1.18. Icon Images

An icon is usually a simple picture representing a program, action, data file or a concept. Icons are intended to help users of visual browsers to recognize features at a glance.

Use an empty alt attribute when an icon is supplemental to text conveying the same meaning.

<a href="home.html"><img src="home.gif" width="15" height="15" alt="">Home</a>

#home:before {
  content: url(home.png);
}

<a href="home.html" id="home">Home</a>

<p>
  <img src="warning.png" width="38" height="34" alt="">
  <strong>Warning!</strong> Your session is about to expire.
</p>

When an icon conveys additional information not available in text, provide a text alternative.

<p>
  <img src="warning.png" width="38" height="34" alt="Warning!">
  <strong>Your session is about to expire.</strong>
</p>

4.7.5.1.19. Logos, insignia, flags, or emblems

Many pages include logos, insignia, flags, or emblems, which stand for a company, organization, project, band, software package, country, or other entity. What can be considered as an appropriate text alternative depends upon, like all images, the context in which the image is being used and what function it serves in the given context.

If a logo is the sole content of a link, provide a brief description of the link target in the alt attribute.

<a href="https://w3c.github.io/html/"><img src="HTML5_Logo.png" alt="HTML 5.1 specification"></a>

If a logo is being used to represent the entity, e.g., as a page heading, provide the name of the entity being represented by the logo as the text alternative.

<h2>
  <img src="images/webplatform.png" alt="WebPlatform.org">
  and other developer resources
</h2>

If a logo is being used next to the name of the what that it represents, then the logo is supplemental. Include an empty alt attribute as the text alternative is already provided.

<img src="images/webplatform1.png" alt=""> WebPlatform.org

If the logo is used alongside text discussing the subject or entity the logo represents, then provide a text alternative which describes the logo.

<p>
  <img src="HTML5_Logo.png" alt="HTML5 logo: Shaped like a shield with the
  text 'HTML' above and the numeral '5' prominent on the face of the shield.">
</p>
<p>
  <strong>HTML</strong> is a language for structuring and presenting content...
</p>

4.7.5.1.20. CAPTCHA Images

CAPTCHA stands for "Completely Automated Public Turing test to tell Computers and Humans Apart". CAPTCHA images are used for security purposes to confirm that content is being accessed by a person rather than a computer. This authentication is done through visual verification of an image. CAPTCHA typically presents an image with characters or words in it that the user is to re-type. The image is usually distorted and has some noise applied to it to make the characters difficult to read.

To improve the accessibility of CAPTCHA provide text alternatives that identify and describe the purpose of the image, and provide alternative forms of the CAPTCHA using output modes for different types of sensory perception. For instance provide an audio alternative along with the visual image. Place the audio option right next to the visual one. This helps but is still problematic for people without sound cards, the deaf-blind, and some people with limited hearing. Another method is to include a form that asks a question along with the visual image. This helps but can be problematic for people with cognitive impairments.

It is strongly recommended that alternatives to CAPTCHA be used, as all forms of CAPTCHA introduce unacceptable barriers to entry for users with disabilities. Further information is available in Inaccessibility of CAPTCHA.

<img src="captcha.png" alt="If you cannot view this image an audio challenge is provided.">
<!-- audio CAPTCHA option that allows the user to listen and type the word -->
<!-- form that asks a question -->

4.7.5.1.21. An image in a picture element

The picture element and any source elements it contains have no semantics for users, only the img element or its text alternative is displayed to users. Provide a text alternative for an img element without regard to it being within a picture element. Refer to Requirements for providing text to act as an alternative for images for more information on how to provide useful alt text for images.

Art directed images that rely on picture need to depict the same content (irrespective of size, pixel density, or any other discriminating factor). Therefore the appropriate text alternative for an image will always be the same irrespective of which source file ends up being chosen by the browser.

<h2>Is it a ghost?</h2>
<picture>
  <source media="(min-width: 32em)" srcset="large.jpg">
  <img src="small.jpg" alt="Reflection of a girl’s face in a train window.">
</picture>

4.7.5.1.22. Guidance for markup generators

Wherever possible, markup generators (such as WYSIWYG authoring tools) should obtain alternative text from their users. However, it is recognized that in many cases obtaining alternative text from users may not be possible.

For images that are the sole contents of links, markup generators should examine the link target to determine the title of the target, or the URL of the target, and use information obtained in this manner as the alternative text.

For images that have captions, markup generators should use the figure and figcaption elements to provide the image’s caption.

As a last resort, implementors must omit the alt attribute altogether. [ATAG20]

<img src="bar-graph.png" alt="">

<img src="bar-graph.png">

Markup generators may specify a generator-unable-to-provide-required-alt attribute on img elements for which they have been unable to obtain a text alternative and for which they have therefore omitted the alt attribute. The value of this attribute must be the empty string. Documents containing such attributes are not conforming, but conformance checkers will silently ignore this error.

This is intended to avoid markup generators from being pressured into replacing the error of omitting the alt attribute with the even more egregious error of providing phony text alternatives, because state-of-the-art automated conformance checkers cannot distinguish phony text alternatives from correct text alternatives.

Markup generators should generally avoid using the image’s own file name as the text alternative. Similarly, markup generators should avoid generating text alternatives from any content that will be equally available to presentation user agents (e.g., Web browsers).

This is because once a page is generated, it will typically not be updated, whereas the browsers that later read the page can be updated by the user, therefore the browser is likely to have more up-to-date and finely-tuned heuristics than the markup generator did when generating the page.

4.7.5.1.23. Guidance for conformance checkers

A conformance checker must report the lack of an alt attribute as an error unless one of the conditions listed below applies:

• The img element is in a figure element that satisfies the conditions described above.

• The img element has a (non-conforming) generator-unable-to-provide-required-alt attribute whose value is the empty string. A conformance checker that is not reporting the lack of an alt attribute as an error must also not report the presence of the empty generator-unable-to-provide-required-alt attribute as an error. (This case does not represent a case where the document is conforming, only that the generator could not determine appropriate alternative text — validators are not required to show an error in this case, because such an error might encourage markup generators to include bogus alternative text purely in an attempt to silence validators. Naturally, conformance checkers may report the lack of an alt attribute as an error even in the presence of the generator-unable-to-provide-required-alt attribute; for example, there could be a user option to report all conformance errors even those that might be the more or less inevitable result of using a markup generator.)

4.7.6. The iframe element

Categories:

Flow content.

Phrasing content.

Embedded content.

Interactive content.

Palpable content.

Contexts in which this element can be used:

Where embedded content is expected.

Content model:

Text that conforms to the requirements given in the prose.

Tag omission in text/html:

Neither tag is omissible

Content attributes:

Global attributes

src - Address of the resource

srcdoc - A document to render in the iframe

name - Name of nested browsing context

sandbox - Security rules for nested content

allowfullscreen - Whether to allow the iframe’s contents to use requestFullscreen()

allowpaymentrequest - Whether the iframe’s contents are allowed to use the PaymentRequest interface to make payment requests

allowusermedia - Whether to allow the iframe's browsing context to use getUserMedia()

width - Horizontal dimension

height - Vertical dimension

referrerpolicy - Referrer policy for fetches initiated by the element

Allowed ARIA role attribute values:

application, document or img.

Allowed ARIA state and property attributes:

Global aria-* attributes

Any aria-* attributes applicable to the allowed roles.

DOM interface:

interface HTMLIFrameElement : HTMLElement {
  attribute DOMString src;
  attribute DOMString srcdoc;
  attribute DOMString name;
  [SameObject, PutForwards=value] readonly attribute DOMTokenList sandbox;
  attribute boolean allowFullscreen;
  attribute boolean allowPaymentRequest;
  attribute boolean allowUserMedia;
  attribute DOMString width;
  attribute DOMString height;
  attribute DOMString referrerPolicy;
  readonly attribute Document? contentDocument;
  readonly attribute WindowProxy? contentWindow;
};

The iframe element represents a nested browsing context.

The src attribute gives the address of a page that the nested browsing context is to contain. The attribute, if present, must be a valid non-empty URL potentially surrounded by spaces.

The srcdoc attribute gives the content of the page that the nested browsing context is to contain. The value of the attribute is the source of an iframe srcdoc document.

The srcdoc attribute, if present, must have a value using the HTML syntax that consists of the following syntactic components, in the given order:

1. Any number of comments and space characters.
2. Optionally, a DOCTYPE. Any DOCTYPE will be ignored, and it will be parsed as if it had

   <!DOCTYPE html>

3. Any number of comments and space characters.
4. The document element, in the form of an html element.
5. Any number of comments and space characters.

<article>
  <h1>I got my own magazine!</h1>
  <p>After much effort, I’ve finally found a publisher, and so now I have my own magazine! Isn’t that awesome?! The first issue will come out in September, and we have articles about getting food, and about getting in boxes, it’s going to be great!</p>
  <footer>
    <p>Written by <a href="/users/cap">cap</a>, 1 hour ago.
  </footer>
  <article>
    <footer>Thirteen minutes ago, <a href="/users/ch">ch</a> wrote:</footer>
    <iframe sandbox srcdoc="<p>did you get a cover picture yet?"></iframe>
  </article>
  <article>
    <footer>Nine minutes ago, <a href="/users/cap">cap</a> wrote:</footer>
    <iframe sandbox srcdoc="<p>Yeah, you can see it <a href=&quot;/gallery?mode=cover&amp;amp;page=1&quot;>in my gallery</a>."></iframe>
  </article>
  <article>
    <footer>Five minutes ago, <a href="/users/ch">ch</a> wrote:</footer>
    <iframe sandbox srcdoc="<p>hey that’s earl’s table.
<p>you should get earl&amp;amp;me on the next cover."></iframe>
  </article>

In the HTML syntax, authors need only remember to use U+0022 QUOTATION MARK characters (") to wrap the attribute contents and then to escape all U+0026 AMPERSAND (&) and U+0022 QUOTATION MARK (") characters, and to specify the sandbox attribute, to ensure safe embedding of content.

Due to restrictions of the XHTML syntax, in XML the U+003C LESS-THAN SIGN character (<) needs to be escaped as well. In order to prevent attribute-value normalization, some of XML’s white space characters — specifically U+0009 CHARACTER TABULATION (tab), U+000A LINE FEED (LF), and U+000D CARRIAGE RETURN (CR) — also need to be escaped. [XML]

If the src attribute and the srcdoc attribute are both specified together, the srcdoc attribute takes priority. This allows authors to provide a fallback URL for legacy user agents that do not support the srcdoc attribute.

When an iframe element is inserted into a document that has a browsing context, the user agent must create a nested browsing context, and then process the iframe attributes for the "first time".

When an iframe element is removed from a document, the user agent must discard the nested browsing context, if any.

This happens without any unload events firing (the nested browsing context and its Document are discarded, not unloaded).

Whenever an iframe element with a nested browsing context has its srcdoc attribute set, changed, or removed, the user agent must process the iframe attributes.

Similarly, whenever an iframe element with a nested browsing context but with no srcdoc attribute specified has its src attribute set, changed, or removed, the user agent must process the iframe attributes.

When the user agent is to process the iframe attributes, it must run the first appropriate steps from the following list:

If the srcdoc attribute is specified

Navigate the element’s child browsing context to a new response whose url list consists of about:srcdoc, header list consists of Content-Type/text/html, body is the value of the attribute, CSP list is the CSP list of the iframe element’s node document, and HTTPS state is the HTTPS state of the iframe element’s node document.

The resulting Document must be considered an iframe srcdoc document.

Otherwise, if the element has no src attribute specified, and the user agent is processing the iframe’s attributes for the "first time"

Queue a task to run the iframe load event steps.

The task source for this task is the DOM manipulation task source.

Otherwise

Run the otherwise steps for iframe or frame elements.

The otherwise steps for iframe or frame elements are as follows:

1: If the element has no src attribute specified, or its value is the empty string, let url be the URL "about:blank".

Otherwise, parse the value of the src attribute, relative to the element’s node document.

If that is not successful, then let url be the URL "about:blank". Otherwise, let url be the resulting URL record.

2. If there exists an ancestor browsing context whose active document’s URL, ignoring fragments, is equal to url, then abort these steps.

3. Let resource be a new request whose url is URL and whose referrer policy is the current state of the element’s referrerpolicy content attribute.

4. Navigate the element’s child browsing context to resource.

Furthermore, if the active document of the element’s child browsing context before such a navigation was not completely loaded at the time of the new navigation, then the navigation must be completed with replacement enabled.

Similarly, if the child browsing context’s session history contained only one Document when the process the iframe attributes algorithm was invoked, and that was the about:blank Document created when the child browsing context was created, then any navigation required of the user agent in that algorithm must be completed with replacement enabled.

When a Document in an iframe is marked as completely loaded, the user agent must run the iframe load event steps in parallel.

A load event is also fired at the iframe element when it is created if no other data is loaded in it.

Each Document has an iframe load in progress flag and a mute iframe load flag. When a Document is created, these flags must be unset for that Document.

The iframe load event steps are as follows:

1. Let child document be the active document of the iframe element’s nested browsing context.
2. If child document has its mute iframe load flag set, abort these steps.
3. Set child document’s iframe load in progress flag.
4. Fire a simple event named load at the iframe element.
5. Unset child document’s iframe load in progress flag.

This, in conjunction with scripting, can be used to probe the URL space of the local network’s HTTP servers. User agents may implement cross-origin access control policies that are stricter than those described above to mitigate this attack, but unfortunately such policies are typically not compatible with existing Web content.

When the iframe’s browsing context’s active document is not ready for post-load tasks, and when anything in the iframe is delaying the load event of the iframe’s browsing context’s active document, and when the iframe’s browsing context is in the delaying load events mode, the iframe must delay the load event of its document.

If, during the handling of the load event, the browsing context in the iframe is again navigated, that will further delay the load event.

If, when the element is created, the srcdoc attribute is not set, and the src attribute is either also not set or set but its value cannot be parsed, the browsing context will remain at the initial about:blank page.

If the user navigates away from this page, the iframe’s corresponding WindowProxy object will proxy new Window objects for new Document objects, but the src attribute will not change.

The name attribute, if present, must be a valid browsing context name. The given value is used to name the nested browsing context. When the browsing context is created, if the attribute is present, the browsing context name must be set to the value of this attribute; otherwise, the browsing context name must be set to the empty string.

Whenever the name attribute is set, the nested browsing context’s name must be changed to the new value. If the attribute is removed, the browsing context name must be set to the empty string.

The sandbox attribute, when specified, enables a set of extra restrictions on any content hosted by the iframe. Its value must be an unordered set of unique space-separated tokens that are ASCII case-insensitive. The allowed values are allow-forms, allow-pointer-lock, allow-popups, allow-presentation, allow-same-origin, allow-scripts, and allow-top-navigation.

When the attribute is set, the content is treated as being from a unique origin, forms, scripts, and various potentially annoying APIs are disabled, links are prevented from targeting other browsing contexts, and plugins are secured. The allow-same-origin keyword causes the content to be treated as being from its real origin instead of forcing it into a unique origin; the allow-top-navigation keyword allows the content to navigate its top-level browsing context; and the allow-forms, allow-pointer-lock, allow-popups, allow-presentation and allow-scripts keywords re-enable forms, the pointer lock API, popups, the presentation API, and scripts respectively. [POINTERLOCK] [PRESENTATION-API]

Setting both the allow-scripts and allow-same-origin keywords together when the embedded page has the same origin as the page containing the iframe allows the embedded page to simply remove the sandbox attribute and then reload itself, effectively breaking out of the sandbox altogether.

These flags only take effect when the nested browsing context of the iframe is navigated. Removing them, or removing the entire sandbox attribute, has no effect on an already-loaded page.

Potentially hostile files should not be served from the same server as the file containing the iframe element. Sandboxing hostile content is of minimal help if an attacker can convince the user to just visit the hostile content directly, rather than in the iframe. To limit the damage that can be caused by hostile HTML content, it should be served from a separate dedicated domain. Using a different domain ensures that scripts in the files are unable to attack the site, even if the user is tricked into visiting those pages directly, without the protection of the sandbox attribute.

When an iframe element with a sandbox attribute has its nested browsing context created (before the initial about:blank Document is created), and when an iframe element’s sandbox attribute is set or changed while it has a nested browsing context, the user agent must parse the sandboxing directive using the attribute’s value as the input, the iframe element’s nested browsing context’s iframe sandboxing flag set as the output, and, if the iframe has an allowfullscreen attribute, the allow fullscreen flag.

When an iframe element’s sandbox attribute is removed while it has a nested browsing context, the user agent must empty the iframe element’s nested browsing context’s iframe sandboxing flag set as the output.

<p>We’re not scared of you! Here is your content, unedited:</p>
<iframe title="Example iframe" sandbox src="https://usercontent.example.net/getusercontent.cgi?id=12345"></iframe>

<iframe title="Maps" sandbox="allow-same-origin allow-forms allow-scripts"
        src="https://maps.example.com/embedded.html"></iframe>;

<iframe title="Example iframe" sandbox="allow-same-origin allow-forms" src="B"></iframe>

<iframe title="Example iframe" sandbox="allow-scripts" src="C"></iframe>

<a href="D">Link</a>

The allowfullscreen attribute is a boolean attribute. When specified, it indicates that Document objects in the iframe element’s browsing context are to be allowed to use requestFullscreen() (if it’s not blocked for other reasons, e.g., there is another ancestor iframe without this attribute set).

<p>Check out my new video!</p>
<iframe title="Video" src="https://video.example.com/embed?id=123456" allowfullscreen></iframe>

The allowpaymentrequest attribute is a boolean attribute. When specified, it indicates that Document objects in the iframe element’s browsing context are to be allowed to use the PaymentRequest interface to make payment requests.

The allowusermedia attribute is a boolean attribute. When specified, it indicates that Document objects in the iframe element’s browsing context are to be allowed to use getUserMedia() (if it’s not blocked for other reasons, e.g. there is another ancestor iframe without this attribute set).

To determine whether a Document object document is allowed to use the feature indicated by attribute name allowattribute, run these steps:

1. If document has no browsing context, then return false.

2. If document’s browsing context is a top-level browsing context, then return true.

3. If document’s browsing context has a browsing context container that is an iframe element with an allowattribute attribute specified, and whose node document is allowed to use the feature indicated by allowattribute, then return true.

4. Return false.

The iframe element supports dimension attributes for cases where the embedded content has specific dimensions (e.g., ad units have well-defined dimensions).

An iframe element never has fallback content, as it will always create a nested browsing context, regardless of whether the specified initial contents are successfully used.

The referrerpolicy attribute is a referrer policy attribute. Its purpose is to set the referrer policy used when processing the iframe attributes. [REFERRERPOLICY]

Descendants of iframe elements represent nothing. (In legacy user agents that do not support iframe elements, the contents would be parsed as markup that could act as fallback content.)

When used in HTML documents, the allowed content model of iframe elements is text, except that invoking the HTML fragment parsing algorithm with the iframe element as the context element and the text contents as the input must result in a list of nodes that are all phrasing content, with no parse errors having occurred, with no script elements being anywhere in the list or as descendants of elements in the list, and with all the elements in the list (including their descendants) being themselves conforming.

The iframe element must be empty in XML documents.

The HTML parser treats markup inside iframe elements as text.

The IDL attributes src, srcdoc, name, and sandbox must reflect the respective content attributes of the same name.

The supported tokens for sandbox's DOMTokenList are the allowed values defined in the sandbox attribute and supported by the user agent.

The allowFullscreen IDL attribute must reflect the allowfullscreen content attribute.

The allowPaymentRequest IDL attribute must reflect the allowpaymentrequest content attribute.

The allowUserMedia IDL attribute must reflect the allowusermedia content attribute.

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

The contentDocument IDL attribute must return the Document object of the active document of the iframe element’s nested browsing context, if any and if its origin is the same origin-domain as the origin specified by the incumbent settings object, or null otherwise.

The contentWindow IDL attribute must return the WindowProxy object of the iframe element’s nested browsing context, if any, or null otherwise.

<iframe title="Advert" src="https://ads.example.com/?customerid=123456&amp;format=banner"
        width="468" height="60"></iframe>

4.7.7. The embed element

Categories:

Flow content.

Phrasing content.

Embedded content.

Interactive content.

Palpable content.

Contexts in which this element can be used:

Where embedded content is expected.

Content model:

Nothing.

Tag omission in text/html:

No end tag

Content attributes:

Global attributes

src - Address of the resource

type - Type of embedded resource

width - Horizontal dimension

height- Vertical dimension

Any other attribute that has no namespace (see prose).

Allowed ARIA role attribute values:

application, document, img, none or presentation.

Allowed ARIA state and property attributes:

Global aria-* attributes

Any aria-* attributes applicable to the allowed roles.

DOM interface:

interface HTMLEmbedElement : HTMLElement {
  attribute DOMString src;
  attribute DOMString type;
  attribute DOMString width;
  attribute DOMString height;
  legacycaller any (any... arguments);
};

Depending on the type of content instantiated by the embed element, the node may also support other interfaces.

The embed element provides an integration point for an external (typically non-HTML) application or interactive content.

The src attribute gives the address of the resource being embedded. The attribute, if present, must contain a valid non-empty URL potentially surrounded by spaces.

The type attribute, if present, gives the MIME type by which the plugin to instantiate is selected. The value must be a valid mime type. If both the type attribute and the src attribute are present, then the type attribute must specify the same type as the explicit Content-Type metadata of the resource given by the src attribute.

While any of the following conditions are occurring, any plugin instantiated for the element must be removed, and the embed element represents nothing:

• The element has neither a src attribute nor a type attribute.
• The element has a media element ancestor.
• The element has an ancestor object element that is not showing its fallback content.

An embed element is said to be potentially active when the following conditions are all met simultaneously:

• The element is in a Document or was in a Document the last time the event loop reached step 1.
• The element’s node document is fully active.
• The element has either a src attribute set or a type attribute set (or both).
• The element’s src attribute is either absent or its value is not the empty string.
• The element is not a descendant of a media element.
• The element is not a descendant of an object element that is not showing its fallback content.
• The element is being rendered, or was being rendered the last time the event loop reached step 1.

Whenever an embed element that was not potentially active becomes potentially active, and whenever a potentially active embed element that is remaining potentially active and has its src attribute set, changed, or removed or its type attribute set, changed, or removed, the user agent must queue a task using the embed task source to run the embed element setup steps.

The embed element setup steps are as follows:

1. If another task has since been queued to run the embed element setup steps for this element, then abort these steps.

2. If the element has a src attribute set

   The user agent must parse the value of the element’s src attribute, relative to the element. If that is successful, the user agent should run these steps:

   1. Let request be a new request whose URL is the resulting URL string, client is the element’s node document’s Window object’s environment settings object, destination is "unknown", omit-Origin-header flag is set if the element doesn’t have a browsing context scope origin, credentials mode is "include", and whose use-URL-credentials flag is set.
   2. Fetch request.

   The task that is queued by the networking task source once the resource has been fetched must run the following steps:

   1. If another task has since been queued to run the embed element setup steps for this element, then abort these steps.

   2. Determine the type of the content being embedded, as follows (stopping at the first substep that determines the type):

      1. If the element has a type attribute, and that attribute’s value is a type that a plugin supports, then the value of the type attribute is the content’s type.

      2. Otherwise, if applying the URL parser algorithm to the URL of the specified resource (after any redirects) results in a URL record whose path component matches a pattern that a plugin supports, then the content’s type is the type that the plugin can handle.

         For example, a plugin might say that it can handle resources with path components that end with the four character string ".swf".

      3. Otherwise, if the specified resource has explicit Content-Type metadata, then that is the content’s type.
      4. Otherwise, the content has no type and there can be no appropriate plugin for it.

   3. If the previous step determined that the content’s type is image/svg+xml, then run the following substeps:

      1. If the embed element is not associated with a nested browsing context, associate the element with a newly created nested browsing context, and, if the element has a name attribute, set the browsing context name of the element’s nested browsing context to the value of this attribute.
      2. Navigate the nested browsing context to the fetched resource, with replacement enabled, and with the embed element’s node document’s browsing context as the source browsing context. (The src attribute of the embed element doesn’t get updated if the browsing context gets further navigated to other locations.)
      3. The embed element now represents its associated nested browsing context.

   4. Otherwise, find and instantiate an appropriate plugin based on the content’s type, and hand that plugin the content of the resource, replacing any previously instantiated plugin for the element. The embed element now represents this plugin instance.

   5. Once the resource or plugin has completely loaded, queue a task to fire a simple event named load at the element.

   Whether the resource is fetched successfully or not (e.g., whether the response status was an ok status) must be ignored when determining the content’s type and when handing the resource to the plugin.

   This allows servers to return data for plugins even with error responses (e.g., HTTP 500 Internal Server Error codes can still contain plugin data).

   Fetching the resource must delay the load event of the element’s node document.

   If the element has no src attribute set

   The user agent should find and instantiate an appropriate plugin based on the value of the type attribute. The embed element now represents this plugin instance.

   Once the plugin is completely loaded, queue a task to fire a simple event named load at the element.

The embed element has no fallback content. If the user agent can’t find a suitable plugin when attempting to find and instantiate one for the algorithm above, then the user agent must use a default plugin. This default could be as simple as saying "Unsupported Format".

Whenever an embed element that was potentially active stops being potentially active, any plugin that had been instantiated for that element must be unloaded.

When a plugin is to be instantiated but it cannot be secured and the sandboxed plugins browsing context flag is set on the embed element’s node document’s active sandboxing flag set, then the user agent must not instantiate the plugin, and must instead render the embed element in a manner that conveys that the plugin was disabled. The user agent may offer the user the option to override the sandbox and instantiate the plugin anyway; if the user invokes such an option, the user agent must act as if the conditions above did not apply for the purposes of this element.

Plugins that cannot be secured are disabled in sandboxed browsing contexts because they might not honor the restrictions imposed by the sandbox (e.g., they might allow scripting even when scripting in the sandbox is disabled). User agents should convey the danger of overriding the sandbox to the user if an option to do so is provided.

When an embed element represents a nested browsing context: if the embed element’s nested browsing context’s active document is not ready for post-load tasks, and when anything is delaying the load event of the embed element’s browsing context’s active document, and when the embed element’s browsing context is in the delaying load events mode, the embed must delay the load event of its document.

The task source for the tasks mentioned in this section is the DOM manipulation task source.

Any namespace-less attribute other than name, align, hspace, and vspace may be specified on the embed element, so long as its name is XML-compatible and contains no uppercase ASCII letters. These attributes are then passed as parameters to the plugin.

All attributes in HTML documents get lowercased automatically, so the restriction on uppercase letters doesn’t affect such documents.

The four exceptions are to exclude legacy attributes that have side-effects beyond just sending parameters to the plugin.

The user agent should pass the names and values of all the attributes of the embed element that have no namespace to the plugin used, when one is instantiated.

The HTMLEmbedElement object representing the element must expose the scriptable interface of the plugin instantiated for the embed element, if any. At a minimum, this interface must implement the legacy caller operation. (It is suggested that the default behavior of this legacy caller operation, e.g., the behavior of the default plugin’s legacy caller operation, be to throw a NotSupportedError exception.)

The embed element supports dimension attributes.

The IDL attributes src and type each must reflect the respective content attributes of the same name.

<embed src="catgame.swf">

<embed src="catgame.swf" quality="high">

<object data="catgame.swf">
  <param name="quality" value="high">
</object>

4.7.8. The object element

Categories:

Flow content.

Phrasing content.

Embedded content.

listed, submittable, and reassociateable form-associated element.

Palpable content.

Contexts in which this element can be used:

Where embedded content is expected.

Content model:

Zero or more param elements, then, transparent.

Tag omission in text/html:

Neither tag is omissible.

Content attributes:

Global attributes

data - Address of the resource

type - Type of embedded resource

typemustmatch - Whether the type attribute and the Content-Type value need to match for the resource to be used

name - Name of nested browsing context

form - Associates the control with a form element

width - Horizontal dimension

height - Vertical dimension

Allowed ARIA role attribute values:

application, document or img.

Allowed ARIA state and property attributes:

Global aria-* attributes

Any aria-* attributes applicable to the allowed roles.

DOM interface:

interface HTMLObjectElement : HTMLElement {
  attribute DOMString data;
  attribute DOMString type;
  attribute boolean typeMustMatch;
  attribute DOMString name;
  readonly attribute HTMLFormElement? form;
  attribute DOMString width;
  attribute DOMString height;
  readonly attribute Document? contentDocument;
  readonly attribute WindowProxy? contentWindow;

  readonly attribute boolean willValidate;
  readonly attribute ValidityState validity;
  readonly attribute DOMString validationMessage;
  boolean checkValidity();
  boolean reportValidity();
  void setCustomValidity(DOMString error);

  legacycaller any (any... arguments);
};

Depending on the type of content instantiated by the object element, the node also supports other interfaces.

The object element can represent an external resource, which, depending on the type of the resource, will either be treated as an image, as a nested browsing context, or as an external resource to be processed by a plugin.

The data attribute, if present, specifies the address of the resource. If present, the attribute must be a valid non-empty URL potentially surrounded by spaces.

Authors who reference resources from other origins that they do not trust are urged to use the typemustmatch attribute defined below. Without that attribute, it is possible in certain cases for an attacker on the remote host to use the plugin mechanism to run arbitrary scripts, even if the author has used features such as the Flash "allowScriptAccess" parameter.

The type attribute, if present, specifies the type of the resource. If present, the attribute must be a valid mime type.

At least one of either the data attribute or the type attribute must be present.

The typemustmatch attribute is a boolean attribute whose presence indicates that the resource specified by the data attribute is only to be used if the value of the type attribute and the Content-Type of the aforementioned resource match.

The typemustmatch attribute must not be specified unless both the data attribute and the type attribute are present.

The name attribute, if present, must be a valid browsing context name. The value is used to name the nested browsing context created for the object, if applicable.

<p>
  <object data="old.svg" name="svgobject">A boring icon</object>
</p>

<p>
  <a href="new.svg" target="svgobject">Check out the new icon</a>!
</p>

Whenever one of the following conditions occur:

• the element is created,
• the element is popped off the stack of open elements of an HTML parser or XML parser,
• the element is not on the stack of open elements of an HTML parser or XML parser, and it is either inserted into a document or removed from a document,
• the element’s node document changes whether it is fully active,
• one of the element’s ancestor object elements changes to or from showing its fallback content,
• the element’s classid attribute is set, changed, or removed,
• the element’s classid attribute is not present, and its data attribute is set, changed, or removed,
• neither the element’s classid attribute nor its data attribute are present, and its type attribute is set, changed, or removed,
• the element changes from being rendered to not being rendered, or vice versa,

...the user agent must queue a task to run the following steps to (re)determine what the object element represents. This task being queued or actively running must delay the load event of the element’s node document.

1. If the user has indicated a preference that this object element’s fallback content be shown instead of the element’s usual behavior, then jump to the step below labeled fallback.

   For example, a user could ask for the element’s fallback content to be shown because that content uses a format that the user finds more accessible.

2. If the element has an ancestor media element, or has an ancestor object element that is not showing its fallback content, or if the element is not in a Document with a browsing context, or if the element’s node document is not fully active, or if the element is still in the stack of open elements of an HTML parser or XML parser, or if the element is not being rendered, or if the Should element be blocked a priori by Content Security Policy? algorithm returns "Blocked" when executed on the element, then jump to the step below labeled fallback. [CSP3].

3. If the classid attribute is present, and has a value that isn’t the empty string, then: if the user agent can find a plugin suitable according to the value of the classid attribute, and either plugins aren’t being sandboxed or that plugin can be secured, then that plugin should be used, and the value of the data attribute, if any, should be passed to the plugin. If no suitable plugin can be found, or if the plugin reports an error, jump to the step below labeled fallback.

4. If the data attribute is present and its value is not the empty string, then:
   1. If the type attribute is present and its value is not a type that the user agent supports, and is not a type that the user agent can find a plugin for, then the user agent may jump to the step below labeled fallback without fetching the content to examine its real type.
   2. Parse the URL specified by the data attribute, relative to the element.
   3. If that failed, fire a simple event named error at the element, then jump to the step below labeled fallback.
   4. Let request be a new request whose URL is the resulting URL string, client is the element’s node document’s Window object’s environment settings object, destination is "unknown", omit-Origin-header flag is set if the element doesn’t have a browsing context scope origin, credentials mode is "include", and whose use-URL-credentials flag is set.
   5. Fetch request.

      Fetching the resource must delay the load event of the element’s node document until the task that is queued by the networking task source once the resource has been fetched (defined next) has been run.

   6. If the resource is not yet available (e.g., because the resource was not available in the cache, so that loading the resource required making a request over the network), then jump to the step below labeled fallback. The task that is queued by the networking task source once the resource is available must restart this algorithm from this step. Resources can load incrementally; user agents may opt to consider a resource "available" whenever enough data has been obtained to begin processing the resource.
   7. If the load failed (e.g., there was an HTTP 404 error, there was a DNS error), fire a simple event named error at the element, then jump to the step below labeled fallback.

   8. Determine the resource type, as follows:

      1. Let the resource type be unknown.

      2. If the object element has a type attribute and a typemustmatch attribute, and the resource has associated Content-Type metadata, and the type specified in the resource’s Content-Type metadata is an ASCII case-insensitive match for the value of the element’s type attribute, then let resource type be that type and jump to the step below labeled handler.

      3. If the object element has a typemustmatch attribute, jump to the step below labeled handler.

      4. If the user agent is configured to strictly obey Content-Type headers for this resource, and the resource has associated Content-Type metadata, then let the resource type be the type specified in the resource’s Content-Type metadata, and jump to the step below labeled handler.

         This can introduce a vulnerability, wherein a site is trying to embed a resource that uses a particular plugin, but the remote site overrides that and instead furnishes the user agent with a resource that triggers a different plugin with different security characteristics.

      5. If there is a type attribute present on the object element, and that attribute’s value is not a type that the user agent supports, but it is a type that a plugin supports, then let the resource type be the type specified in that type attribute, and jump to the step below labeled handler.

      6. Run the appropriate set of steps from the following list:

         If the resource has associated Content-Type metadata

         1. Let binary be false.

         2. If the type specified in the resource’s Content-Type metadata is "text/plain", and the result of applying the rules for distinguishing if a resource is text or binary to the resource is that the resource is not text/plain, then set binary to true.

         3. If the type specified in the resource’s Content-Type metadata is "application/octet-stream", then set binary to true.

         4. If binary is false, then let the resource type be the type specified in the resource’s Content-Type metadata, and jump to the step below labeled handler.

         5. If there is a type attribute present on the object element, and its value is not application/octet-stream, then run the following steps:

            1. If the attribute’s value is a type that a plugin supports, or the attribute’s value is a type that starts with "image/" that is not also an XML MIME type, then let the resource type be the type specified in that type attribute.

            2. Jump to the step below labeled handler.

         Otherwise, if the resource does not have associated Content-Type metadata

         1. If there is a type attribute present on the object element, then let the tentative type be the type specified in that type attribute.

            Otherwise, let tentative type be the computed type of the resource.

         2. If tentative type is not application/octet-stream, then let resource type be tentative type and jump to the step below labeled handler.

      7. If applying the URL parser algorithm to the URL of the specified resource (after any redirects) results in a URL record whose path component matches a pattern that a plugin supports, then let resource type be the type that the plugin can handle.

         For example, a plugin might say that it can handle resources with path components that end with the four character string ".swf".

      It is possible for this step to finish, or for one of the substeps above to jump straight to the next step, with resource type still being unknown. In both cases, the next step will trigger fallback.

   9. Handler: Handle the content as given by the first of the following cases that matches:

      If the resource type is not a type that the user agent supports, but it is a type that a plugin supports

      If plugins are being sandboxed and the plugin that supports resource type cannot be secured, jump to the step below labeled fallback.

      Otherwise, the user agent should use the plugin that supports resource type and pass the content of the resource to that plugin. If the plugin reports an error, then jump to the step below labeled fallback.

      If the resource type is an XML MIME type, or if the resource type does not start with "image/"

      The object element must be associated with a newly created nested browsing context, if it does not already have one.

      If the URL of the given resource is not about:blank, the element’s nested browsing context must then be navigated to that resource, with replacement enabled, and with the object element’s node document’s browsing context as the source browsing context. (The data attribute of the object element doesn’t get updated if the browsing context gets further navigated to other locations.)

      If the URL of the given resource is about:blank, then, instead, the user agent must queue a task to fire a simple event named load at the object element. No load event is fired at the about:blank document itself.

      The object element represents the nested browsing context.

      If the name attribute is present, the browsing context name must be set to the value of this attribute; otherwise, the browsing context name must be set to the empty string.

      If the resource type starts with "image/", and support for images has not been disabled

      Apply the image sniffing rules to determine the type of the image.

      The object element represents the specified image. The image is not a nested browsing context.

      If the image cannot be rendered, e.g., because it is malformed or in an unsupported format, jump to the step below labeled fallback.

      Otherwise

      The given resource type is not supported. Jump to the step below labeled fallback.

      If the previous step ended with the resource type being unknown, this is the case that is triggered.

   10. The element’s contents are not part of what the object element represents.

   11. Abort these steps. Once the resource is completely loaded, queue a task to fire a simple event named load at the element.

5. If the data attribute is absent but the type attribute is present, and the user agent can find a plugin suitable according to the value of the type attribute, and either plugins aren’t being sandboxed or the plugin can be secured, then that plugin should be used. If these conditions cannot be met, or if the plugin reports an error, jump to the step below labeled fallback. Otherwise abort these steps; once the plugin is completely loaded, queue a task to fire a simple event named load at the element.
6. Fallback: The object element represents the element’s children, ignoring any leading param element children. This is the element’s fallback content. If the element has an instantiated plugin, then unload it.

When the algorithm above instantiates a plugin, the user agent should pass to the plugin used the names and values of all the attributes on the element, in the order they were added to the element, with the attributes added by the parser being ordered in source order, followed by a parameter named "PARAM" whose value is null, followed by all the names and values of parameters given by param elements that are children of the object element, in tree order. If the plugin supports a scriptable interface, the HTMLObjectElement object representing the element should expose that interface. The object element represents the plugin. The plugin is not a nested browsing context.

Plugins are considered sandboxed for the purpose of an object element if the sandboxed plugins browsing context flag is set on the object element’s node document’s active sandboxing flag set.

Due to the algorithm above, the contents of object elements act as fallback content, used only when referenced resources can’t be shown (e.g., because it returned a 404 error). This allows multiple object elements to be nested inside each other, targeting multiple user agents with different capabilities, with the user agent picking the first one it supports.

When an object element represents a nested browsing context: if the object element’s nested browsing context’s active document is not ready for post-load tasks, and when anything is delaying the load event of the object element’s browsing context’s active document, and when the object element’s browsing context is in the delaying load events mode, the object must delay the load event of its document.

The task source for the tasks mentioned in this section is the DOM manipulation task source.

Whenever the name attribute is set, if the object element has a nested browsing context, its name must be changed to the new value. If the attribute is removed, if the object element has a browsing context, the browsing context name must be set to the empty string.

The form attribute is used to explicitly associate the object element with its form owner.

Constraint validation: object elements are always barred from constraint validation.

The object element supports dimension attributes.

The IDL attributes data, type and name each must reflect the respective content attributes of the same name. The typeMustMatch IDL attribute must reflect the typemustmatch content attribute.

The contentDocument IDL attribute must return the Document object of the active document of the object element’s nested browsing context, if any and if its origin is the same origin-domain as the origin specified by the incumbent settings object, or null otherwise.

The contentWindow IDL attribute must return the WindowProxy object of the object element’s nested browsing context, if it has one; otherwise, it must return null.

The willValidate, validity, and validationMessage attributes, and the checkValidity(), reportValidity(), and setCustomValidity() methods, are part of the constraint validation API. The form IDL attribute is part of the element’s forms API.

All object elements have a legacy caller operation. If the object element has an instantiated plugin that supports a scriptable interface that defines a legacy caller operation, then that must be the behavior of the object’s legacy caller operation. Otherwise, the object’s legacy caller operation must be to throw a NotSupportedError exception.

<figure>
  <object type="application/x-java-applet">
    <param name="code" value="MyJavaClass">
    <p>You do not have Java available, or it is disabled.</p>
  </object>
  <figcaption>My Java Clock</figcaption>
</figure>

<figure>
  <object data="clock.html"></object>
  <figcaption>My HTML Clock</figcaption>
</figure>

<p>Look at my video:
  <object type="application/x-shockwave-flash">
    <param name="movie" value="https://video.example.com/library/watch.swf">
    <param name="allowfullscreen" value="true">
    <param name="flashvars" value="https://video.example.com/vids/123456">
    <video controls src="https://video.example.com/vids/123456">
      <a href="https://video.example.com/vids/123456">View video</a>.
    </video>
  </object>
</p>

4.7.9. The param element

Categories:

None.

Contexts in which this element can be used:

As a child of an object element, before any flow content.

Content model:

Nothing.

Tag omission in text/html:

No end tag

Content attributes:

Global attributes

name - Name of parameter

value - Value of parameter

Allowed ARIA role attribute values:

None

Allowed ARIA state and property attributes:

None

DOM interface:

interface HTMLParamElement : HTMLElement {
  attribute DOMString name;
  attribute DOMString value;
};

The param element defines parameters for plugins invoked by object elements. It does not represent anything on its own.

The name attribute gives the name of the parameter.

The value attribute gives the value of the parameter.

Both attributes must be present. They may have any value.

If both attributes are present, and if the parent element of the param is an object element, then the element defines a parameter with the given name-value pair.

If either the name or value of a parameter defined by a param element that is the child of an object element that represents an instantiated plugin changes, and if that plugin is communicating with the user agent using an API that features the ability to update the plugin when the name or value of a parameter so changes, then the user agent must appropriately exercise that ability to notify the plugin of the change.

The IDL attributes name and value must both reflect the respective content attributes of the same name.

<object type="application/vnd.o3d.auto">
  <param name="o3d_features" value="FloatingPointTextures">
  <img src="o3d-teapot.png"
      title="3D Utah Teapot illustration rendered using O3D."
      alt="When O3D renders the Utah Teapot, it appears as a squat
      teapot with a shiny metallic finish on which the
      surroundings are reflected, with a faint shadow caused by
      the lighting.">
  <p>To see the teapot actually rendered by O3D on your computer, please download and install the
  <a href="https://example.com/o3d/install">O3D plugin</a>.</p>
</object>
<script src="o3d-teapot.js"></script>

4.7.10. The video element

Categories:

Flow content.

Phrasing content.

Embedded content.

If the element has a controls attribute: interactive content.

Palpable content.

Contexts in which this element can be used:

Where embedded content is expected.

Content model:

If the element has a src attribute: zero or more track elements, then transparent, but with no media element descendants.

If the element does not have a src attribute: zero or more source elements, then zero or more track elements, then transparent, but with no media element descendants.

Tag omission in text/html:

Neither tag is omissible

Content attributes:

Global attributes

src - Address of the resource

crossorigin - How the element handles crossorigin requests

poster - Poster frame to show prior to video playback

preload - Hints how much buffering the media resource will likely need

autoplay - Hint that the media resource can be started automatically when the page is loaded

loop - Whether to loop the media resource

muted - Whether to mute the media resource by default

controls - Show user agent controls

width - Horizontal dimension

height - Vertical dimension

Allowed ARIA role attribute values:

application

Allowed ARIA state and property attributes:

Global aria-* attributes

Any aria-* attributes applicable to the application role.

DOM interface:

interface HTMLVideoElement : HTMLMediaElement {
  attribute unsigned long width;
  attribute unsigned long height;
  readonly attribute unsigned long videoWidth;
  readonly attribute unsigned long videoHeight;
  attribute DOMString poster;
};