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:
Empty.
Content attributes:
Global attributes
alt
src
srcset
crossorigin
usemap
ismap
width
height
DOM interface:
[NamedConstructor=Image(optional unsigned long width, optional unsigned long height)]
interface HTMLImageElement : HTMLElement {
           attribute DOMString alt;
           attribute DOMString src;
           attribute DOMString srcset;
           attribute DOMString crossOrigin;
           attribute DOMString useMap;
           attribute boolean isMap;
           attribute unsigned long width;
           attribute unsigned long height;
  readonly attribute unsigned long naturalWidth;
  readonly attribute unsigned long naturalHeight;
  readonly attribute boolean complete;
};

An img element represents an image.

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

The requirements on the alt attribute's value are described in 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 (,). This attribute allows authors to provide alternative images for environments with smaller screens or screens with higher pixel densities.

The srcset attribute allows authors to provide a set of images to handle graphical displays of varying dimensions and pixel densities.

The attribute essentially takes a comma-separated list of URLs each with one or more descriptors giving the maximum viewport dimensions and pixel density allowed to use the image. From the available options, the user agent then picks the most appropriate image. If the viewport dimensions or pixel density changes, the user agent can replace the image data with a new image on the fly.

To specify an image, give first a URL, then one or more descriptors of the form 100w, 100h, or 2x, where "100w" means "maximum viewport width of 100 CSS pixels", "100h" is the same but for height, and "2x" means "maximum pixel density of 2 device pixels per CSS pixel".

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 referencing a non-interactive, optionally animated, image resource that is neither paged nor scripted.
  3. Zero or more space characters.
  4. Optionally a width descriptor, consisting of: a space character, a valid non-negative integer representing the width descriptor value, and a U+0077 LATIN SMALL LETTER W character.
  5. Zero or more space characters.
  6. Optionally a height descriptor, consisting of: a space character, a valid non-negative integer representing the height descriptor value, and a U+0068 LATIN SMALL LETTER H character.
  7. Zero or more space characters.
  8. Optionally 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.
  9. Zero or more space characters.

Each image candidate string must have at least one of the three optional descriptors. There must not be two image candidate strings in a srcset attribute whose width descriptor value, height descriptor value, and pixel density descriptor value are each identical to their counterpart in the other image candidate string; for the purposes of this requirement, omitted width descriptors and height descriptors are considered to have the value "Infinity", and omitted pixel density descriptors are considered to have the value 1.

In this example, a banner that takes half the viewport is provided in two versions, one for wide screen and one for narrow screens.

<h1><img alt="The Breakfast Combo"
         src="banner.jpeg"
         srcset="banner-HD.jpeg 2x, banner-phone.jpeg 100w, banner-phone-HD.jpeg 100w 2x"></h1>

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 root element), animated bitmaps (APNGs, animated GIFs), animated vector graphics (XML files with an SVG root element that use declarative SMIL animation), and so forth. However, these definitions preclude SVG files with script, multipage PDF files, interactive MNG files, HTML documents, plain text documents, and so forth. [PNG] [GIF] [JPEG] [PDF] [XML] [APNG] [SVG] [MNG]

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

An img is always in one of the following states:

Unavailable
The user agent hasn't obtained any image data.
Partially available
The user agent has obtained some of the image data.
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).

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

An img element is initially unavailable.

When an img element is available, it provides a paint source whose width is the image's intrinsic width, whose height is the image's intrinsic height, 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 synchronously update the image data of an img element whenever that element is created with a src attribute, a srcset attribute, or both. A user agent that obtains images immediately must also synchronously update the image data of an img element whenever that element has its src, srcset, or crossorigin attribute set, changed, or removed, and whenever that element's adopting steps are run.

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 has a src or srcset attribute, and only if the img element is in the unavailable state. When an img element's src, srcset, or crossorigin attribute set, changed, or removed, and whenever that element's adopting steps are run, if the user agent only obtains images on demand, the img element must return to the unavailable state.

Each img element has a last selected source, which must initially be null, and 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.

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 an intrinsic dimension of 96 CSS pixels by 192 CSS pixels.

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. 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. User agents may also remove images from such lists at any time (e.g. to save memory).

When the user agent is to update the image data of an img element, it must run the following steps:

  1. Return the img element to the unavailable state.

  2. If an instance of the fetching algorithm is still running for this element, then abort that algorithm, discarding any pending tasks generated by that algorithm.

  3. Forget the img element's current image data, if any.

  4. If the user agent cannot support images, or its support for images has been disabled, then abort these steps.

  5. If the element has a srcset attribute specified, then let selected source and selected pixel density be the URL and pixel density that results from processing the image candidates, respectively. Otherwise, if the element 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.

  6. Let the img element's last selected source be selected source and the img element's current pixel density be selected pixel density.

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

    1. Resolve selected source, relative to the element. If that is not successful, abort these steps.

    2. Let key be a tuple consisting of the resulting absolute URL, the img element's crossorigin attribute's mode, and, if that mode is not No CORS, the Document object's origin.

    3. If the list of available images contains an entry for key, then set the img element to the completely available state, update the presentation of the image appropriately, queue a task to fire a simple event named load at the img element, and abort these steps.

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

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

  10. ⌛ If selected source is null, then set the element to the broken state, queue a task to fire a simple event named error at the img element, and abort these steps.

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

  12. ⌛ Do a potentially CORS-enabled fetch of the absolute URL that resulted from the earlier step, with the mode being the current state of the element's crossorigin content attribute, the origin being the origin of the img element's Document, and the default origin behaviour set to taint.

    The resource obtained in this fashion, if any, is the img element'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 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 must fire a progress event named progress at the img element.

  13. End the synchronous section, continuing the remaining steps asynchronously, but without missing any data from the fetch algorithm.

  14. 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 set the img element's state to partially available.

    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 set the img element's state to partially available.

    That task, and each subsequent task, that is queued by the networking task source while the image is being fetched 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 the steps for the matching entry in the following list:

    If the download was successful and the user agent was able to determine the image's width and height

    1. Set the img element to the completely available state.

    2. Add the image to the list of available images using the key key.

    3. If the resource is CORS-same-origin: fire a progress event named load at the img element.

      If the resource is CORS-cross-origin: fire a simple event named load at the img element.

    4. If the resource is CORS-same-origin: fire a progress event named loadend at the img element.

      If the resource is CORS-cross-origin: fire a simple event named loadend at the img element.

    Otherwise

    1. Set the img element to the broken state.

    2. If the resource is CORS-same-origin: fire a progress event named load at the img element.

      If the resource is CORS-cross-origin: fire a simple event named load at the img element.

    3. If the resource is CORS-same-origin: fire a progress event named loadend at the img element.

      If the resource is CORS-cross-origin: fire a simple event named loadend at the img element.

    Otherwise

    Either the image data is corrupted in some fatal way such that the image dimensions cannot be obtained, or the image data is not in a supported file format; the user agent must set the img element to the broken state, abort the fetching algorithm, discarding any pending tasks generated by that algorithm, 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.

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

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 code was a 2xx code or equivalent) 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 root 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.

When the user agent is required to process the image candidates of an img element's srcset attribute, the user agent must run the following steps, which return a URL and pixel density (null and undefined respectively if no selection can be made):

  1. Let input be the value of the img element's srcset attribute.

  2. Let position be a pointer into input, initially pointing at the start of the string.

  3. Let raw candidates be an initially empty ordered list of URLs with associated unparsed descriptors. The order of entries in the list is the order in which entries are added to the list.

  4. Splitting loop: Skip whitespace.

  5. Collect a sequence of characters that are not space characters, and let that be url.

  6. If url is empty, then jump to the step labeled descriptor parser.

  7. Collect a sequence of characters that are not U+002C COMMA characters (,), and let that be descriptors.

  8. Add url to raw candidates, associated with descriptors.

  9. If position is past the end of input, then jump to the step labeled descriptor parser.

  10. Advance position to the next character in input (skipping past the U+002C COMMA character (,) separating this candidate from the next).

  11. Return to the step labeled splitting loop.

  12. Descriptor parser: Let candidates be an initially empty ordered list of URLs each with an associated pixel density, and optionally an associated width, height, or both. The order of entries in the list is the order in which entries are added to the list.

  13. For each entry in raw candidates with URL url associated with the unparsed descriptors unparsed descriptors, in the order they were originally added to the list, run these substeps:

    1. Let descriptor list be the result of splitting unparsed descriptors on spaces.

    2. Let error be no.

    3. Let width be absent.

    4. Let height be absent.

    5. Let density be absent.

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

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

      1. If width is not absent, then let error be yes.

      2. Apply the rules for parsing non-negative integers to the token. Let width be the result.

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

      1. If height is not absent, then let error be yes.

      2. Apply the rules for parsing non-negative integers to the token. Let height be the result.

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

      1. If density is not absent, then let error be yes.

      2. Apply the rules for parsing floating-point number values to the token. Let density be the result.

    7. If width is still absent, set it to Infinity.

    8. If height is still absent, set it to Infinity.

    9. If density is still absent, set it to 1.0.

    10. If error is still no, then add an entry to candidates whose URL is url, associated with a width width, a height height, and a pixel density density.

  14. If the img element has a src attribute whose value is not the empty string, then run the following substeps:

    1. Let url be the value of the element's src attribute.

    2. Add an entry to candidates whose URL is url, associated with a width Infinity, a height Infinity, and a pixel density 1.0.

  15. If candidates is empty, return null as the URL and undefined as the pixel density and abort these steps.

  16. If an entry b in candidates has the same associated width, height, and pixel density as an earlier entry a in candidates, then remove entry b. Repeat this step until none of the entries in candidates have the same associated width, height, and pixel density as an earlier entry.

  17. Optionally, return the URL of an entry in candidates chosen by the user agent, and that entry's associated pixel density, and then abort these steps. The user agent may apply any algorithm or heuristic in its selection of an entry for the purposes of this step.

    This allows a user agent to override the default algorithm (as described in subsequent steps) in case the user agent has a reason to do so. For example, it would allow the user agent in highly bandwidth-constrained conditions to intentionally opt to use an image intended for a smaller screen size, on the assumption that it'll probably be good enough. Implementors are urged to avoid doing this if at all possible, to let authors have predictable results. The results of using an image intended for a different viewport size can be, at a minimum, aesthetically displeasing.

    This clause is not necessary to select images that are of lower pixel density than the display can handle, because the definition of pixel density below is also left up to the user agent. This step is only needed to allow user agents to pick images intended for viewports with other dimensions.

  18. Let max width be the width of the viewport, and let max height be the height of the viewport. [CSS]

  19. If there are any entries in candidates that have an associated width that is less than max width, then remove them, unless that would remove all the entries, in which case remove only the entries whose associated width is less than the greatest such width.

  20. If there are any entries in candidates that have an associated height that is less than max height, then remove them, unless that would remove all the entries, in which case remove only the entries whose associated height is less than the greatest such height.

  21. If there are any entries in candidates that have an associated pixel density that is less than a user-agent-defined value giving the nominal pixel density of the display, then remove them, unless that would remove all the entries, in which case remove only the entries whose associated pixel density is less than the greatest such pixel density.

  22. Remove all the entries in candidates that have an associated width that is greater than the smallest such width.

  23. Remove all the entries in candidates that have an associated height that is greater than the smallest such height.

  24. Remove all the entries in candidates that have an associated pixel density that is greater than the smallest such pixel density.

  25. Return the URL of the sole remaining entry in candidates, and that entry's associated pixel density.

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

  1. Asynchronously 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 have a srcset attribute specified, is not in the completely available state, has image data whose resource type is multipart/x-mixed-replace, or if its update the image data algorithm is running, then abort this algorithm.

  3. ⌛ Let selected source and selected pixel density be the URL and pixel density that results from processing the image candidates, 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. ⌛ Resolve selected source, relative to the element.

  7. ⌛ Let CORS mode be the state of the element's crossorigin content attribute.

  8. ⌛ If the resolve a URL algorithm is not successful, abort these steps.

  9. End the synchronous section, continuing the remaining steps asynchronously.

  10. Do a potentially CORS-enabled fetch of the resulting absolute URL, with the mode being CORS mode, the origin being the origin of the img element's Document, and the default origin behaviour set to taint.

    If this download fails in any way (other than the response code not being a 2xx code, as mentioned earlier), or if the image format is unsupported (as determined by applying the image sniffing rules, again as mentioned earlier), or if the resource type is multipart/x-mixed-replace, then abort these steps.

    Otherwise, wait for the fetch algorithm to queue its last task, and then continue with these steps. The data obtained in this way is used in the steps below.

  11. Queue a task to run the following substeps:

    1. If the img element's src, srcset, or crossorigin attributes have been set, changed, or removed since this algorithm started, then 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. Replace the img element's image data with the resource obtained by the earlier step of this algorithm. 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).

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

The image is either decorative or supplemental to the rest of the content, redundant with some other information in the document.

If the image is available and the user agent is configured to display that image, then the element represents the element's image data.

Otherwise, the element represents nothing, and may be omitted completely from the rendering. User agents may provide the user with a notification that an image is present but has been omitted from the rendering.

If the src attribute is set and the alt attribute is set to a value that isn't empty

The image is a key part of the content; the alt attribute gives a textual equivalent or replacement for the image.

If the image is available and the user agent is configured to display that image, then the element represents the element's image data.

Otherwise, the element represents the text given by the alt attribute. User agents may provide the user with a notification that an image is present but has been omitted from the rendering.

If the src attribute is set and the alt attribute is not

The image might be a key part of the content, and there is no textual equivalent of the image available.

In a conforming document, the absence of the alt attribute indicates that the image is a key part of the content but that a textual replacement for the image was not available when the image was generated.

If the image is available and the user agent is configured to display that image, then the element represents the element's image data.

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 has a title attribute whose value is not the empty string, then the value of that attribute is the caption information; abort these steps.

  2. If the image is a descendant of a figure element that has a child figcaption element, and, ignoring the figcaption element and its descendants, the figure element has no flow content descendants other than inter-element whitespace and the img element, then the contents of the first such figcaption element are the caption information; abort these steps.

  3. There is no caption information.

If the src attribute is not set and either the alt attribute is set to the empty string or the alt attribute is not set at all

The element represents nothing.

Otherwise

The element represents the text given by the alt attribute.

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

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

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

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

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

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

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

The img element supports dimension attributes.

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

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

The useMap IDL attribute must reflect the usemap content attribute.

The isMap IDL attribute must reflect the ismap 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 = 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 intrinsic width and height of the image, in CSS pixels, if the image is available but not being rendered to a visual medium; or else 0, if the image is not available. [CSS]

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 intrinsic width and height of the image, in CSS pixels, if the image is available, or else 0. [CSS]

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

Otherwise, the attribute must return false.

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

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

A single image can have different appropriate alternative text depending on the context.

In each of the following cases, the same image is used, yet the alt text is different each time. The image is the coat of arms of the Carouge municipality in the canton Geneva in Switzerland.

Here it is used as a supplementary icon:

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

Here it is used as an icon representing the town:

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

Here it is used as part of a text on the town:

<p>Carouge has a coat of arms.</p>
<p><img src="carouge.svg" alt="The coat of arms depicts a lion, sitting in front of a tree."></p>
<p>It is used as decoration all over the town.</p>

Here it is used as a way to support a similar text where the description is given as well as, instead of as an alternative to, the image:

<p>Carouge has a coat of arms.</p>
<p><img src="carouge.svg" alt=""></p>
<p>The coat of arms depicts a lion, sitting in front of a tree.
It is used as decoration all over the town.</p>

Here it is used as part of a story:

<p>He picked up the folder and a piece of paper fell out.</p>
<p><img src="carouge.svg" alt="Shaped like a shield, the paper had a
red background, a green tree, and a yellow lion with its tongue
hanging out and whose tail was shaped like an S."></p>
<p>He stared at the folder. S! The answer he had been looking for all
this time was simply the letter S! How had he not seen that before? It all
came together now. The phone call where Hector had referred to a lion's tail,
the time Marco had stuck his tongue out...</p>

Here it is not known at the time of publication what the image will be, only that it will be a coat of arms of some kind, and thus no replacement text can be provided, and instead only a brief caption for the image is provided, in the title attribute:

<p>The last user to have uploaded a coat of arms uploaded this one:</p>
<p><img src="last-uploaded-coat-of-arms.cgi" title="User-uploaded coat of arms."></p>

Ideally, the author would find a way to provide real replacement text even in this case, e.g. by asking the previous user. Not providing replacement text makes the document more difficult to use for people who are unable to view images, e.g. blind users, or users or very low-bandwidth connections or who pay by the byte, or users who are forced to use a text-only Web browser.

Here are some more examples showing the same picture used in different contexts, with different appropriate alternate texts each time.

<article>
 <h1>My cats</h1>
 <h2>Fluffy</h2>
 <p>Fluffy is my favorite.</p>
 <img src="fluffy.jpg" alt="She likes playing with a ball of yarn.">
 <p>She's just too cute.</p>
 <h2>Miles</h2>
 <p>My other cat, Miles just eats and sleeps.</p>
</article>
<article>
 <h1>Photography</h1>
 <h2>Shooting moving targets indoors</h2>
 <p>The trick here is to know how to anticipate; to know at what speed and
 what distance the subject will pass by.</p>
 <img src="fluffy.jpg" alt="A cat flying by, chasing a ball of yarn, can be
 photographed quite nicely using this technique.">
 <h2>Nature by night</h2>
 <p>To achieve this, you'll need either an extremely sensitive film, or
 immense flash lights.</p>
</article>
<article>
 <h1>About me</h1>
 <h2>My pets</h2>
 <p>I've got a cat named Fluffy and a dog named Miles.</p>
 <img src="fluffy.jpg" alt="Fluffy, my cat, tends to keep itself busy.">
 <p>My dog Miles and I like go on long walks together.</p>
 <h2>music</h2>
 <p>After our walks, having emptied my mind, I like listening to Bach.</p>
</article>
<article>
 <h1>Fluffy and the Yarn</h1>
 <p>Fluffy was a cat who liked to play with yarn. He also liked to jump.</p>
 <aside><img src="fluffy.jpg" alt="" title="Fluffy"></aside>
 <p>He would play in the morning, he would play in the evening.</p>
</article>