1. 4.8.4 Images
        1. 4.8.4.1 Introduction
          1. 4.8.4.1.1 Adaptive images
        2. 4.8.4.2 Attributes common to source and img elements
          1. 4.8.4.2.1 Srcset attributes
          2. 4.8.4.2.2 Sizes attributes
        3. 4.8.4.3 Processing model
          1. 4.8.4.3.1 When to obtain images
          2. 4.8.4.3.2 Reacting to DOM mutations
          3. 4.8.4.3.3 The list of available images
          4. 4.8.4.3.4 Decoding images
          5. 4.8.4.3.5 Updating the image data
          6. 4.8.4.3.6 Selecting an image source
          7. 4.8.4.3.7 Updating the source set
          8. 4.8.4.3.8 Parsing a srcset attribute
          9. 4.8.4.3.9 Parsing a sizes attribute
          10. 4.8.4.3.10 Normalizing the source densities
          11. 4.8.4.3.11 Reacting to environment changes
        4. 4.8.4.4 Requirements for providing text to act as an alternative for images
          1. 4.8.4.4.1 General guidelines
          2. 4.8.4.4.2 A link or button containing nothing but the image
          3. 4.8.4.4.3 A phrase or paragraph with an alternative graphical representation: charts, diagrams, graphs, maps, illustrations
          4. 4.8.4.4.4 A short phrase or label with an alternative graphical representation: icons, logos
          5. 4.8.4.4.5 Text that has been rendered to a graphic for typographical effect
          6. 4.8.4.4.6 A graphical representation of some of the surrounding text
          7. 4.8.4.4.7 Ancillary images
          8. 4.8.4.4.8 A purely decorative image that doesn't add any information
          9. 4.8.4.4.9 A group of images that form a single larger picture with no links
          10. 4.8.4.4.10 A group of images that form a single larger picture with links
          11. 4.8.4.4.11 A key part of the content
          12. 4.8.4.4.12 An image not intended for the user
          13. 4.8.4.4.13 An image in an e-mail or private document intended for a specific person who is known to be able to view images
          14. 4.8.4.4.14 Guidance for markup generators
          15. 4.8.4.4.15 Guidance for conformance checkers

4.8.4 Images

4.8.4.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 its src attribute.

<h2>From today's featured article</h2>
<img src="/uploads/100-marie-lloyd.jpg" alt="" width="100" height="150">
<p><b><a href="/wiki/Marie_Lloyd">Marie Lloyd</a></b> (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:

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:

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="" width="100" height="150">
<p><b><a href="/wiki/Marie_Lloyd">Marie Lloyd</a></b> (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.

For backwards compatibility with older user agents that don't yet 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 lower-resolution than the user would like) being displayed even in older user agents. For new user agents, the src attribute participates in the resource selection, as if it was specified in 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 sizes="100vw" srcset="wolf-400.jpg 400w, wolf-800.jpg 800w, wolf-1600.jpg 1600w"
     src="wolf-400.jpg" 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 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="" width="100" height="150">
</picture>
<p><b><a href="/wiki/Marie_Lloyd">Marie Lloyd</a></b> (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.8.4.1.1 Adaptive images

This section is non-normative.

CSS and media queries can be used to construct graphical page layouts that adapt dynamically to the user's environment, in particular to different viewport dimensions and pixel densities. For content, however, CSS does not help; instead, we have the img element's srcset attribute and the picture element. This section walks through a sample case showing how to use these features.

Consider a situation where on wide screens (wider than 600 CSS pixels) a 300×150 image named a-rectangle.png is to be used, but on smaller screens (600 CSS pixels and less), a smaller 100×100 image called a-square.png is to be used. The markup for this would look like this:

<figure>
 <picture>
  <source srcset="a-square.png" media="(max-width: 600px)">
  <img src="a-rectangle.png" alt="Barney Frank wears a suit and glasses.">
 </picture>
 <figcaption>Barney Frank, 2011</figcaption>
</figure>

For details on what to put in the alt attribute, see the Requirements for providing text to act as an alternative for images section.

The problem with this is that the user agent does not necessarily know what dimensions to use for the image when the image is loading. To avoid the layout having to be reflowed multiple times as the page is loading, CSS and CSS media queries can be used to provide the dimensions:

<style>
 #a { width: 300px; height: 150px; }
 @media (max-width: 600px) { #a { width: 100px; height: 100px; } }
</style>
<figure>
 <picture>
  <source srcset="a-square.png" media="(max-width: 600px)">
  <img src="a-rectangle.png" alt="Barney Frank wears a suit and glasses." id="a">
 </picture>
 <figcaption>Barney Frank, 2011</figcaption>
</figure>

Alternatively, the width and height attributes can be used to provide the width for legacy user agents, using CSS just for the user agents that support picture:

<style media="(max-width: 600px)">
 #a { width: 100px; height: 100px; }
</style>
<figure>
 <picture>
  <source srcset="a-square.png" media="(max-width: 600px)">
  <img src="a-rectangle.png" width="300" height="150"
  alt="Barney Frank wears a suit and glasses." id="a">
 </picture>
 <figcaption>Barney Frank, 2011</figcaption>
</figure>

The img element is used with the src attribute, which gives the URL of the image to use for legacy user agents that do not support the picture element. This leads to a question of which image to provide in the src attribute.

If the author wants the biggest image in legacy user agents, the markup could be as follows:

<picture>
 <source srcset="pear-mobile.jpeg" media="(max-width: 720px)">
 <source srcset="pear-tablet.jpeg" media="(max-width: 1280px)">
 <img src="pear-desktop.jpeg" alt="The pear is juicy.">
</picture>

However, if legacy mobile user agents are more important, one can list all three images in the source elements, overriding the src attribute entirely.

<picture>
 <source srcset="pear-mobile.jpeg" media="(max-width: 720px)">
 <source srcset="pear-tablet.jpeg" media="(max-width: 1280px)">
 <source srcset="pear-desktop.jpeg">
 <img src="pear-mobile.jpeg" alt="The pear is juicy.">
</picture>

Since at this point the src attribute is actually being ignored entirely by picture-supporting user agents, the src attribute can default to any image, including one that is neither the smallest nor biggest:

<picture>
 <source srcset="pear-mobile.jpeg" media="(max-width: 720px)">
 <source srcset="pear-tablet.jpeg" media="(max-width: 1280px)">
 <source srcset="pear-desktop.jpeg">
 <img src="pear-tablet.jpeg" alt="The pear is juicy.">
</picture>

Above the max-width media feature is used, giving the maximum (viewport) dimensions that an image is intended for. It is also possible to use min-width instead.

<picture>
 <source srcset="pear-desktop.jpeg" media="(min-width: 1281px)">
 <source srcset="pear-tablet.jpeg" media="(min-width: 721px)">
 <img src="pear-mobile.jpeg" alt="The pear is juicy.">
</picture>
4.8.4.2 Attributes common to source and img elements
4.8.4.2.1 Srcset attributes

A srcset attribute is an attribute with requirements defined in this section.

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 ASCII whitespace after the URL, the following image candidate string, if there is one, must begin with one or more ASCII whitespace.

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

  1. Zero or more ASCII whitespace.

  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 ASCII whitespace.

  4. Zero or one of the following:

  5. Zero or more ASCII whitespace.

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 an image candidate string for an 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.

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

4.8.4.2.2 Sizes attributes

A sizes attribute is an attribute with requirements defined in this section.

If present, the value must be a valid source size list.

A valid source size list is a string that matches the following grammar: [CSSVALUES] [MQ]

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

A <source-size-value> must not be negative, and must not use CSS functions other than the 'calc()' function.

The <source-size-value> gives the intended layout width of the image. The author can specify different widths for different environments with <media-condition>s.

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.

4.8.4.3 Processing model

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


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.

Spec bugs: 27484

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's state is either partially available or completely available, the image request is said to be available.

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

An image request's state is initially unavailable.

When an img element's current request is available, the img element 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.


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.


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, if the current pixel density is 3.125, that means that there are 300 device pixels per CSS inch, and thus if the image data is 300x600, it has intrinsic dimensions of 96 CSS pixels by 192 CSS pixels.

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 pixel 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 node document's viewport. Other units must be interpreted the same as in Media Queries. [MQ]


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


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.

Spec bugs: 25889, 26702

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 honour any animation in the resource.

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

4.8.4.3.1 When to obtain images

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 synchronously 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's current request's state is unavailable. When an img element has experienced relevant mutations, if the user agent only obtains images on demand, the img element's current request's state must return to unavailable.

4.8.4.3.2 Reacting to DOM mutations

The relevant mutations for an img element are as follows:

4.8.4.3.3 The list of available images

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.

The user agent can also store the image data separately from the list of available images.

For example, if a resource has the HTTP response header `Cache-Control: must-revalidate`, and its ignore higher-layer caching flag is unset, 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 304 Not Modified status.

4.8.4.3.4 Decoding images

Image data is usually encoded in order to reduce file size. This means that in order for the user agent to present the image to the screen, the data needs to be decoded. Decoding is the process which converts an image's media data into a bitmap form, suitable for presentation to the screen. Note that this process can be slow relative to other processes involved in presenting content. Thus, the user agent can choose when to perform decoding, in order to create 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:

Keyword State Description
sync Sync Indicates a preference to decode this image synchronously for atomic presentation with other content.
async Async Indicates a preference to decode this image asynchronously to avoid delaying presentation of other content.
auto Auto Indicates no preference in decoding mode (the default).

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.

It is also possible to control the decoding behavior using the decode() method. Since the decode() method performs decoding independently from the process responsible for presenting content to screen, it is unaffected by the decoding attribute.

4.8.4.3.5 Updating the image data

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:

Spec bugs: 24597, 24712

  1. If the element's node document is not the active document, then:

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

    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's state to unavailable, set pending request to null, and return.

  3. Let selected source be null and selected pixel density be undefined.

  4. If the element does not use srcset or picture and it has a src attribute specified whose value is not the empty string, then set selected source to the value of the element's src attribute and set selected pixel density to 1.0.

  5. Set the element's last selected source to selected source.

  6. If selected source is not null, then:

    1. Parse selected source, relative to the element's node document. If that is not successful, then abort this 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, then:

      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. Set pending request to null.

      4. Let current request be a new image request whose image data is that of the entry and whose state is completely available.

      5. Update the presentation of the image appropriately.

      6. Set current request's current pixel density to selected pixel density.

      7. Queue a task to:

        1. If restart animation is set, then restart the animation.

        2. Set current request's current URL to urlString.

        3. Fire an event named load at the img element.

      8. Abort the update the image data algorithm.

  7. 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 ⌛.)

  8. ⌛ 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 return.

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

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

  10. ⌛ If selected source is null, then:

    1. ⌛ Set the current request's state to broken, abort the image request for the current request and the pending request, and set pending request to 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 an event named error at the img element.

    3. ⌛ Abort this algorithm.

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

  12. Parse selected source, relative to the element's node document, and let urlString be the resulting URL string. If that is not successful, then:

    1. Abort the image request for the current request and the pending request.

    2. ⌛ Set the current request's state to broken.

    3. ⌛ Set pending request to null.

    4. Queue a task to change the current request's current URL to selected source, fire an event named error at the img element and then fire an event named loadend at the img element.

    5. ⌛ Abort the update the image data algorithm.

  13. ⌛ If the pending request is not null and urlString is the same as the pending request's current URL, then return.

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

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

  16. ⌛ Set image request to a new image request whose current URL is urlString.

  17. ⌛ If current request's state is unavailable or broken, then set the current request to image request. Otherwise, set the pending request to image request.

  18. ⌛ Let request be the result of creating a potential-CORS request given urlString, "image", and the current state of the element's crossorigin content attribute.

  19. ⌛ Set request's client to the element's node document's Window object's environment settings object.

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

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

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

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

  24. 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, its state is unavailable, 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, its state is unavailable, 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's current request's state to completely available and queue a task to fire an 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's state to broken, fire an event named error at the img element, fire an 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 an event named error at the img element, fire an 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).

    Spec bugs: 25797, 25798

    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 event named load at the img element, depending on the resource in image request.

    5. Fire a progress event or 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's state to broken, 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 an event named error at the img element and then fire an event named loadend at the img element.

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

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 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 an event named type at e.

4.8.4.3.6 Selecting an image source

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.

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

4.8.4.3.7 Updating the source set

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

4.8.4.3.8 Parsing a srcset attribute

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 code points that are ASCII whitespace or U+002C COMMA characters from input given position. If any U+002C COMMA characters were collected, that is a parse error.

  5. If position is past the end of input, return candidates.

  6. Collect a sequence of code points that are not ASCII whitespace from input given position, and let that be url.

  7. Let descriptors be a new empty list.

  8. If url ends with U+002C (,), then:

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

    Otherwise:

    1. Descriptor tokenizer: Skip ASCII whitespace within input given position.

    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:

      ASCII whitespace

      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:

      ASCII whitespace

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

      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.

4.8.4.3.9 Parsing a sizes attribute

When asked to parse a sizes attribute from an element, with a fallback width width, 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. [CSSSYNTAX]

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. [MQ]

  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.

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.

4.8.4.3.10 Normalizing the source densities

An image source can have a pixel density descriptor, a width descriptor, or no descriptor at all accompanying its URL. Normalizing a source set gives every image source a pixel 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 pixel density descriptor, continue to the next image source.

    2. Otherwise, if the image source has a width descriptor, replace the width descriptor with a pixel density descriptor with a value of the width descriptor value 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 pixel density descriptor of 1x.

4.8.4.3.11 Reacting to environment changes

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

  5. ⌛ If selected source and selected pixel density are the same as the element's last selected source and current pixel density, then return.

  6. Parse selected source, relative to the element's node document, and let urlString be the resulting URL string. If that is not successful, return.

  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:

    1. Let request be the result of creating a potential-CORS request given urlString, "image", and corsAttributeState.

    2. Set request's client to client, initiator to "imageset", 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 these steps:

    1. If the img element has experienced relevant mutations since this algorithm started, then let pending request be null and return.

    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 the image request's state to completely available.

    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 an event named load at the img element.

4.8.4.4 Requirements for providing text to act as an alternative for images
4.8.4.4.1 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 replacement for the image. The specific requirements for the alt attribute depend on what the image is intended to represent, as described in the following sections.

The most general rule to consider when writing alternative text is the following: the intent is that replacing every image with the text of its alt attribute not change the meaning of the page.

So, in general, alternative text can be written by considering what one would have written had one not been able to include the image.

A corollary to this is that the alt attribute's value should never contain text that could be considered the image's caption, title, or legend. It is supposed to contain replacement text that could be used by users instead of the image; it is not meant to supplement the image. The title attribute can be used for supplemental information.

Another corollary is that the alt attribute's value should not repeat information that is already provided in the prose next to the image.

One way to think of alternative text is to think about how you would read the page containing the image to someone over the phone, without mentioning that there is an image present. Whatever you say instead of the image is typically a good start for writing the alternative text.

When an a element that creates a hyperlink, or a button element, has no textual content but contains one or more images, the alt attributes must contain text that together convey the purpose of the link or button.

In this example, a user is asked to pick their preferred color from a list of three. Each color is given by an image, but for users who have configured their user agent not to display images, the color names are used instead:

<h1>Pick your color</h1>
<ul>
 <li><a href="green.html"><img src="green.jpeg" alt="Green"></a></li>
 <li><a href="blue.html"><img src="blue.jpeg" alt="Blue"></a></li>
 <li><a href="red.html"><img src="red.jpeg" alt="Red"></a></li>
</ul>

In this example, each button has a set of images to indicate the kind of color output desired by the user. The first image is used in each case to give the alternative text.

<button name="rgb"><img src="red" alt="RGB"><img src="green" alt=""><img src="blue" alt=""></button>
<button name="cmyk"><img src="cyan" alt="CMYK"><img src="magenta" alt=""><img src="yellow" alt=""><img src="black" alt=""></button>

Since each image represents one part of the text, it could also be written like this:

<button name="rgb"><img src="red" alt="R"><img src="green" alt="G"><img src="blue" alt="B"></button>
<button name="cmyk"><img src="cyan" alt="C"><img src="magenta" alt="M"><img src="yellow" alt="Y"><img src="black" alt="K"></button>

However, with other alternative text, this might not work, and putting all the alternative text into one image in each case might make more sense:

<button name="rgb"><img src="red" alt="sRGB profile"><img src="green" alt=""><img src="blue" alt=""></button>
<button name="cmyk"><img src="cyan" alt="CMYK profile"><img src="magenta" alt=""><img src="yellow" alt=""><img src="black" alt=""></button>
4.8.4.4.3 A phrase or paragraph with an alternative graphical representation: charts, diagrams, graphs, maps, illustrations

Sometimes something can be more clearly stated in graphical form, for example as a flowchart, a diagram, a graph, or a simple map showing directions. In such cases, an image can be given using the img element, but the lesser textual version must still be given, so that users who are unable to view the image (e.g. because they have a very slow connection, or because they are using a text-only browser, or because they are listening to the page being read out by a hands-free automobile voice Web browser, or simply because they are blind) are still able to understand the message being conveyed.

The text must be given in the alt attribute, and must convey the same message as the image specified in the src attribute.

It is important to realize that the alternative text is a replacement for the image, not a description of the image.

In the following example we have a flowchart in image form, with text in the alt attribute rephrasing the flowchart in prose form:

<p>In the common case, the data handled by the tokenization stage
comes from the network, but it can also come from script.</p>
<p><img src="images/parsing-model-overview.svg" alt="The Network
passes data to the Input Stream Preprocessor, which passes it to the
Tokenizer, which passes it to the Tree Construction stage. From there,
data goes to both the DOM and to Script Execution. Script Execution is
linked to the DOM, and, using document.write(), passes data to the
Tokenizer."></p>

Here's another example, showing a good solution and a bad solution to the problem of including an image in a description.

First, here's the good solution. This sample shows how the alternative text should just be what you would have put in the prose if the image had never existed.

<!-- This is the correct way to do things. -->
<p>
 You are standing in an open field west of a house.
 <img src="house.jpeg" alt="The house is white, with a boarded front door.">
 There is a small mailbox here.
</p>

Second, here's the bad solution. In this incorrect way of doing things, the alternative text is simply a description of the image, instead of a textual replacement for the image. It's bad because when the image isn't shown, the text doesn't flow as well as in the first example.

<!-- This is the wrong way to do things. -->
<p>
 You are standing in an open field west of a house.
 <img src="house.jpeg" alt="A white house, with a boarded front door.">
 There is a small mailbox here.
</p>

Text such as "Photo of white house with boarded door" would be equally bad alternative text (though it could be suitable for the title attribute or in the figcaption element of a figure with this image).

4.8.4.4.4 A short phrase or label with an alternative graphical representation: icons, logos

A document can contain information in iconic form. The icon is intended to help users of visual browsers to recognize features at a glance.

In some cases, the icon is supplemental to a text label conveying the same meaning. In those cases, the alt attribute must be present but must be empty.

Here the icons are next to text that conveys the same meaning, so they have an empty alt attribute:

<nav>
 <p><a href="/help/"><img src="/icons/help.png" alt=""> Help</a></p>
 <p><a href="/configure/"><img src="/icons/configuration.png" alt="">
 Configuration Tools</a></p>
</nav>

In other cases, the icon has no text next to it describing what it means; the icon is supposed to be self-explanatory. In those cases, an equivalent textual label must be given in the alt attribute.

Here, posts on a news site are labeled with an icon indicating their topic.

<body>
 <article>
  <header>
   <h1>Ratatouille wins <i>Best Movie of the Year</i> award</h1>
   <p><img src="movies.png" alt="Movies"></p>
  </header>
  <p>Pixar has won yet another <i>Best Movie of the Year</i> award,
  making this its 8th win in the last 12 years.</p>
 </article>
 <article>
  <header>
   <h1>Latest TWiT episode is online</h1>
   <p><img src="podcasts.png" alt="Podcasts"></p>
  </header>
  <p>The latest TWiT episode has been posted, in which we hear
  several tech news stories as well as learning much more about the
  iPhone. This week, the panelists compare how reflective their
  iPhones' Apple logos are.</p>
 </article>
</body>

Many pages include logos, insignia, flags, or emblems, which stand for a particular entity such as a company, organization, project, band, software package, country, or some such.

If the logo is being used to represent the entity, e.g. as a page heading, the alt attribute must contain the name of the entity being represented by the logo. The alt attribute must not contain text like the word "logo", as it is not the fact that it is a logo that is being conveyed, it's the entity itself.

If the logo is being used next to the name of the entity that it represents, then the logo is supplemental, and its alt attribute must instead be empty.

If the logo is merely used as decorative material (as branding, or, for example, as a side image in an article that mentions the entity to which the logo belongs), then the entry below on purely decorative images applies. If the logo is actually being discussed, then it is being used as a phrase or paragraph (the description of the logo) with an alternative graphical representation (the logo itself), and the first entry above applies.

In the following snippets, all four of the above cases are present. First, we see a logo used to represent a company:

<h1><img src="XYZ.gif" alt="The XYZ company"></h1>

Next, we see a paragraph which uses a logo right next to the company name, and so doesn't have any alternative text:

<article>
 <h2>News</h2>
 <p>We have recently been looking at buying the <img src="alpha.gif"
 alt=""> ΑΒΓ company, a small Greek company
 specializing in our type of product.</p>

In this third snippet, we have a logo being used in an aside, as part of the larger article discussing the acquisition:

 <aside><p><img src="alpha-large.gif" alt=""></p></aside>
 <p>The ΑΒΓ company has had a good quarter, and our
 pie chart studies of their accounts suggest a much bigger blue slice
 than its green and orange slices, which is always a good sign.</p>
</article>

Finally, we have an opinion piece talking about a logo, and the logo is therefore described in detail in the alternative text.

<p>Consider for a moment their logo:</p>

<p><img src="/images/logo" alt="It consists of a green circle with a
green question mark centered inside it."></p>

<p>How unoriginal can you get? I mean, oooooh, a question mark, how
<em>revolutionary</em>, how utterly <em>ground-breaking</em>, I'm
sure everyone will rush to adopt those specifications now! They could
at least have tried for some sort of, I don't know, sequence of
rounded squares with varying shades of green and bold white outlines,
at least that would look good on the cover of a blue book.</p>

This example shows how the alternative text should be written such that if the image isn't available, and the text is used instead, the text flows seamlessly into the surrounding text, as if the image had never been there in the first place.

4.8.4.4.5 Text that has been rendered to a graphic for typographical effect

Sometimes, an image just consists of text, and the purpose of the image is not to highlight the actual typographic effects used to render the text, but just to convey the text itself.

In such cases, the alt attribute must be present but must consist of the same text as written in the image itself.

Consider a graphic containing the text "Earth Day", but with the letters all decorated with flowers and plants. If the text is merely being used as a heading, to spice up the page for graphical users, then the correct alternative text is just the same text "Earth Day", and no mention need be made of the decorations:

<h1><img src="earthdayheading.png" alt="Earth Day"></h1>

An illuminated manuscript might use graphics for some of its images. The alternative text in such a situation is just the character that the image represents.

<p><img src="initials/o.svg" alt="O">nce upon a time and a long long time ago, late at
night, when it was dark, over the hills, through the woods, across a great ocean, in a land far
away, in a small house, on a hill, under a full moon...

When an image is used to represent a character that cannot otherwise be represented in Unicode, for example gaiji, itaiji, or new characters such as novel currency symbols, the alternative text should be a more conventional way of writing the same thing, e.g. using the phonetic hiragana or katakana to give the character's pronunciation.

In this example from 1997, a new-fangled currency symbol that looks like a curly E with two bars in the middle instead of one is represented using an image. The alternative text gives the character's pronunciation.

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

An image should not be used if characters would serve an identical purpose. Only when the text cannot be directly represented using text, e.g., because of decorations or because there is no appropriate character (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.

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

A flowchart that repeats the previous paragraph in graphical form:

<p>The Network passes data to the Input Stream Preprocessor, which
passes it to the Tokenizer, which passes it to the Tree Construction
stage. From there, data goes to both the DOM and to Script Execution.
Script Execution is linked to the DOM, and, using document.write(),
passes data to the Tokenizer.</p>
<p><img src="images/parsing-model-overview.svg" alt=""></p>

In these cases, it would be wrong to include alternative text that consists of just a caption. If a caption is to be included, then either the title attribute can be used, or the figure and figcaption elements can be used. In the latter case, the image would in fact be a phrase or paragraph with an alternative graphical representation, and would thus require alternative text.

<!-- Using the title="" attribute -->
<p>The Network passes data to the Input Stream Preprocessor, which
passes it to the Tokenizer, which passes it to the Tree Construction
stage. From there, data goes to both the DOM and to Script Execution.
Script Execution is linked to the DOM, and, using document.write(),
passes data to the Tokenizer.</p>
<p><img src="images/parsing-model-overview.svg" alt=""
        title="Flowchart representation of the parsing model."></p>
<!-- Using <figure> and <figcaption> -->
<p>The Network passes data to the Input Stream Preprocessor, which
passes it to the Tokenizer, which passes it to the Tree Construction
stage. From there, data goes to both the DOM and to Script Execution.
Script Execution is linked to the DOM, and, using document.write(),
passes data to the Tokenizer.</p>
<figure>
 <img src="images/parsing-model-overview.svg" alt="The Network leads to
 the Input Stream Preprocessor, which leads to the Tokenizer, which
 leads to the Tree Construction stage. The Tree Construction stage
 leads to two items. The first is Script Execution, which leads via
 document.write() back to the Tokenizer. The second item from which
 Tree Construction leads is the DOM. The DOM is related to the Script
 Execution.">
 <figcaption>Flowchart representation of the parsing model.</figcaption>
</figure>
<!-- This is WRONG. Do not do this. Instead, do what the above examples do. -->
<p>The Network passes data to the Input Stream Preprocessor, which
passes it to the Tokenizer, which passes it to the Tree Construction
stage. From there, data goes to both the DOM and to Script Execution.
Script Execution is linked to the DOM, and, using document.write(),
passes data to the Tokenizer.</p>
<p><img src="images/parsing-model-overview.svg"
        alt="Flowchart representation of the parsing model."></p>
<!-- Never put the image's caption in the alt="" attribute! -->

A graph that repeats the previous paragraph in graphical form:

<p>According to a study covering several billion pages,
about 62% of documents on the Web in 2007 triggered the Quirks
rendering mode of Web browsers, about 30% triggered the Almost
Standards mode, and about 9% triggered the Standards mode.</p>
<p><img src="rendering-mode-pie-chart.png" alt=""></p>
4.8.4.4.7 Ancillary images

Sometimes, an image is not critical to the content, but is nonetheless neither purely decorative nor entirely redundant with the text. In these cases, the alt attribute must be present, and its value should either be the empty string, or a textual representation of the information that the image conveys. If the image has a caption giving the image's title, then the alt attribute's value must not be empty (as that would be quite confusing for non-visual readers).

Consider a news article about a political figure, in which the individual's face was shown in an image that, through a style sheet, is floated to the right. The image is not purely decorative, as it is relevant to the story. The image is not entirely redundant with the story either, as it shows what the politician looks like. Whether any alternative text need be provided is an authoring decision, in part influenced by whether the image colors the interpretation of the prose.

In this first variant, the image is shown without context, and no alternative text is provided:

<p><img src="alexsalmond.jpeg" alt=""> Ahead of today's referendum,
the First Minister of Scotland, Alex Salmond, wrote an open letter to all
registered voters. In it, he admitted that all countries make mistakes.</p>

If the picture is just a face, there might be no value in describing it. It's of no interest to the reader whether the individual has red hair or blond hair, whether the individual has white skin or black skin, whether the individual has one eye or two eyes.

However, if the picture is more dynamic, for instance showing the politician as angry, or particularly happy, or devastated, some alternative text would be useful in setting the tone of the article, a tone that might otherwise be missed:

<p><img src="alexsalmond.jpeg" alt="Alex Salmond is sad.">
Ahead of today's referendum, the First Minister of Scotland, Alex Salmond,
wrote an open letter to all registered voters. In it, he admitted that all
countries make mistakes.</p>
<p><img src="alexsalmond.jpeg" alt="Alex Salmond is ecstatic!">
Ahead of today's referendum, the First Minister of Scotland, Alex Salmond,
wrote an open letter to all registered voters. In it, he admitted that all
countries make mistakes.</p>

Whether the individual was "sad" or "ecstatic" makes a difference to how the rest of the paragraph is to be interpreted: is he likely saying that he is resigned to the populace making a bad choice in the upcoming referendum, or is he saying that the election was a mistake but the likely turnout will make it irrelevant? The interpretation varies based on the image.

If the image has a caption, then including alternative text avoids leaving the non-visual user confused as to what the caption refers to.

<p>Ahead of today's referendum, the First Minister of Scotland, Alex Salmond,
wrote an open letter to all registered voters. In it, he admitted that all
countries make mistakes.</p>
<figure>
 <img src="alexsalmond.jpeg"
      alt="A high forehead, cheerful disposition, and dark hair round out Alex Salmond's face.">
 <figcaption> Alex Salmond, SNP. Photo © 2014 PolitiPhoto. </figcaption>
</figure>
4.8.4.4.8 A purely decorative image that doesn't add any information

If an image is decorative but isn't especially page-specific — for example an image that forms part of a site-wide design scheme — the image should be specified in the site's CSS, not in the markup of the document.

However, a decorative image that isn't discussed by the surrounding text but still has some relevance can be included in a page using the img element. Such images are decorative, but still form part of the content. In these cases, the alt attribute must be present but its value must be the empty string.

Examples where the image is purely decorative despite being relevant would include things like a photo of the Black Rock City landscape in a blog post about an event at Burning Man, or an image of a painting inspired by a poem, on a page reciting that poem. The following snippet shows an example of the latter case (only the first verse is included in this snippet):

<h1>The Lady of Shalott</h1>
<p><img src="shalott.jpeg" alt=""></p>
<p>On either side the river lie<br>
Long fields of barley and of rye,<br>
That clothe the wold and meet the sky;<br>
And through the field the road run by<br>
To many-tower'd Camelot;<br>
And up and down the people go,<br>
Gazing where the lilies blow<br>
Round an island there below,<br>
The island of Shalott.</p>

When a picture has been sliced into smaller image files that are then displayed together to form the complete picture again, one of the images must have its alt attribute set as per the relevant rules that would be appropriate for the picture as a whole, and then all the remaining images must have their alt attribute set to the empty string.

In the following example, a picture representing a company logo for XYZ Corp has been split into two pieces, the first containing the letters "XYZ" and the second with the word "Corp". The alternative text ("XYZ Corp") is all in the first image.

<h1><img src="logo1.png" alt="XYZ Corp"><img src="logo2.png" alt=""></h1>

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

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

Generally, image maps should be used instead of slicing an image for links.

However, if an image is indeed sliced and any of the components of the sliced picture are the sole contents of links, then one image per link must have alternative text in its alt attribute representing the purpose of the link.

In the following example, a picture representing the flying spaghetti monster emblem, with each of the left noodly appendages and the right noodly appendages in different images, so that the user can pick the left side or the right side in an adventure.

<h1>The Church</h1>
<p>You come across a flying spaghetti monster. Which side of His
Noodliness do you wish to reach out for?</p>
<p><a href="?go=left" ><img src="fsm-left.png"  alt="Left side. "></a
  ><img src="fsm-middle.png" alt=""
  ><a href="?go=right"><img src="fsm-right.png" alt="Right side."></a></p>
4.8.4.4.11 A key part of the content

In some cases, the image is a critical part of the content. This could be the case, for instance, on a page that is part of a photo gallery. The image is the whole point of the page containing it.

How to provide alternative text for an image that is a key part of the content depends on the image's provenance.

The general case

When it is possible for detailed alternative text to be provided, for example if the image is part of a series of screenshots in a magazine review, or part of a comic strip, or is a photograph in a blog entry about that photograph, text that can serve as a substitute for the image must be given as the contents of the alt attribute.

A screenshot in a gallery of screenshots for a new OS, with some alternative text:

<figure>
 <img src="KDE%20Light%20desktop.png"
      alt="The desktop is blue, with icons along the left hand side in
           two columns, reading System, Home, K-Mail, etc. A window is
           open showing that menus wrap to a second line if they
           cannot fit in the window. The window has a list of icons
           along the top, with an address bar below it, a list of
           icons for tabs along the left edge, a status bar on the
           bottom, and two panes in the middle. The desktop has a bar
           at the bottom of the screen with a few buttons, a pager, a
           list of open applications, and a clock.">
 <figcaption>Screenshot of a KDE desktop.</figcaption>
</figure>

A graph in a financial report:

<img src="sales.gif"
     title="Sales graph"
     alt="From 1998 to 2005, sales increased by the following percentages
     with each year: 624%, 75%, 138%, 40%, 35%, 9%, 21%">

Note that "sales graph" would be inadequate alternative text for a sales graph. Text that would be a good caption is not generally suitable as replacement text.

Images that defy a complete description

In certain cases, the nature of the image might be such that providing thorough alternative text is impractical. For example, the image could be indistinct, or could be a complex fractal, or could be a detailed topographical map.

In these cases, the alt attribute must contain some suitable alternative text, but it may be somewhat brief.

Sometimes there simply is no text that can do justice to an image. For example, there is little that can be said to usefully describe a Rorschach inkblot test. However, a description, even if brief, is still better than nothing:

<figure>
 <img src="/commons/a/a7/Rorschach1.jpg" alt="A shape with left-right
 symmetry with indistinct edges, with a small gap in the center, two
 larger gaps offset slightly from the center, with two similar gaps
 under them. The outline is wider in the top half than the bottom
 half, with the sides extending upwards higher than the center, and
 the center extending below the sides.">
 <figcaption>A black outline of the first of the ten cards
 in the Rorschach inkblot test.</figcaption>
</figure>

Note that the following would be a very bad use of alternative text:

<!-- This example is wrong. Do not copy it. -->
<figure>
 <img src="/commons/a/a7/Rorschach1.jpg" alt="A black outline
 of the first of the ten cards in the Rorschach inkblot test.">
 <figcaption>A black outline of the first of the ten cards
 in the Rorschach inkblot test.</figcaption>
</figure>

Including the caption in the alternative text like this isn't useful because it effectively duplicates the caption for users who don't have images, taunting them twice yet not helping them any more than if they had only read or heard the caption once.

Another example of an image that defies full description is a fractal, which, by definition, is infinite in detail.

The following example shows one possible way of providing alternative text for the full view of an image of the Mandelbrot set.

<img src="ms1.jpeg" alt="The Mandelbrot set appears as a cardioid with
its cusp on the real axis in the positive direction, with a smaller
bulb aligned along the same center line, touching it in the negative
direction, and with these two shapes being surrounded by smaller bulbs
of various sizes.">

Similarly, a photograph of a person's face, for example in a biography, can be considered quite relevant and key to the content, but it can be hard to fully substitute text for:

<section class="bio">
 <h1>A Biography of Isaac Asimov</h1>
 <p>Born <b>Isaak Yudovich Ozimov</b> in 1920, Isaac was a prolific author.</p>
 <p><img src="headpics/asimov.jpeg" alt="Isaac Asimov had dark hair, a tall forehead, and wore glasses.
 Later in life, he wore long white sideburns.">
 <p>Asimov was born in Russia, and moved to the US when he was three years old.</p>
 <p>...
</section>

In such cases it is unnecessary (and indeed discouraged) to include a reference to the presence of the image itself in the alternative text, since such text would be redundant with the browser itself reporting the presence of the image. For example, if the alternative text was "A photo of Isaac Asimov", then a conforming user agent might read that out as "(Image) A photo of Isaac Asimov" rather than the more useful "(Image) Isaac Asimov had dark hair, a tall forehead, and wore glasses...".

Images whose contents are not known

In some unfortunate cases, there might be no alternative text available at all, either because the image is obtained in some automated fashion without any associated alternative text (e.g. a Webcam), or because the page is being generated by a script using user-provided images where the user did not provide suitable or usable alternative text (e.g. photograph sharing sites), or because the author does not themself know what the images represent (e.g. a blind photographer sharing an image on their blog).

In such cases, the alt attribute may be omitted, but one of the following conditions must be met as well:

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.

A photo on a photo-sharing site, if the site received the image with no metadata other than the caption, could be marked up as follows:

<figure>
 <img src="1100670787_6a7c664aef.jpg">
 <figcaption>Bubbles traveled everywhere with us.</figcaption>
</figure>

It would be better, however, if a detailed description of the important parts of the image obtained from the user and included on the page.

A blind user's blog in which a photo taken by the user is shown. Initially, the user might not have any idea what the photo they took shows:

<article>
 <h1>I took a photo</h1>
 <p>I went out today and took a photo!</p>
 <figure>
  <img src="photo2.jpeg">
  <figcaption>A photograph taken blindly from my front porch.</figcaption>
 </figure>
</article>

Eventually though, the user might obtain a description of the image from their friends and could then include alternative text:

<article>
 <h1>I took a photo</h1>
 <p>I went out today and took a photo!</p>
 <figure>
  <img src="photo2.jpeg" alt="The photograph shows my squirrel
  feeder hanging from the edge of my roof. It is half full, but there
  are no squirrels around. In the background, out-of-focus trees fill the
  shot. The feeder is made of wood with a metal grate, and it contains
  peanuts. The edge of the roof is wooden too, and is painted white
  with light blue streaks.">
  <figcaption>A photograph taken blindly from my front porch.</figcaption>
 </figure>
</article>

Sometimes the entire point of the image is that a textual description is not available, and the user is to provide the description. For instance, the point of a CAPTCHA image is to see if the user can literally read the graphic. Here is one way to mark up a CAPTCHA (note the title attribute):

<p><label>What does this image say?
<img src="captcha.cgi?id=8934" title="CAPTCHA">
<input type=text name=captcha></label>
(If you cannot see the image, you can use an <a
href="?audio">audio</a> test instead.)</p>

Another example would be software that displays images and asks for alternative text precisely for the purpose of then writing a page with correct alternative text. Such a page could have a table of images, like this:

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

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

Since some users cannot use images at all (e.g. because they have a very slow connection, or because they are using a text-only browser, or because they are listening to the page being read out by a hands-free automobile voice Web browser, or simply because they are blind), the alt attribute is only allowed to be omitted rather than being provided with replacement text when no alternative text is available and none can be made available, as in the above examples. Lack of effort from the part of the author is not an acceptable reason for omitting the alt attribute.

4.8.4.4.12 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, then the alt attribute must be the empty string.

In such cases, the width and height attributes should both be set to zero.

4.8.4.4.13 An image in an e-mail or private document intended for a specific person who is known to be able to view images

This section does not apply to documents that are publicly accessible, or whose target audience is not necessarily personally known to the author, such as documents on a Web site, e-mails sent to public mailing lists, or software documentation.

When an image is included in a private communication (such as an HTML e-mail) aimed at a specific person who is known to be able to view images, the alt attribute may be omitted. However, even in such cases authors are strongly urged to include alternative text (as appropriate according to the kind of image involved, as described in the above entries), so that the e-mail is still usable should the user use a mail client that does not support images, or should the document be forwarded on to other users whose abilities might not include easily seeing images.

4.8.4.4.14 Guidance for markup generators

Markup generators (such as WYSIWYG authoring tools) should, wherever possible, obtain alternative text from their users. However, it is recognized that in many cases, this will 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, or the title attribute, to provide the image's caption.

As a last resort, implementers should either set the alt attribute to the empty string, under the assumption that the image is a purely decorative image that doesn't add any information but is still specific to the surrounding content, or omit the alt attribute altogether, under the assumption that the image is a key part of the content.

Markup generators may specify a generator-unable-to-provide-required-alt attribute on img elements for which they have been unable to obtain alternative text 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 alternative text, because state-of-the-art automated conformance checkers cannot distinguish phony alternative text from correct alternative text.

Markup generators should generally avoid using the image's own file name as the alternative text. Similarly, markup generators should avoid generating alternative text 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.8.4.4.15 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: