<img>

The <img> element represents an image.

Point

• The image given by the src attribute is the embedded content, and the value of the alt attribute is the img element's fallback content.

• Example of images:
  • PNG
  • JPEG
  • GIF
  • single-page PDF
  • XML file with an SVG root elemet
  • APNG
  • animated GIF ...

However, this also precludes SVG files with script, multipage PDF files, interactive MNG files, HTML documents, plain text documents, and so forth.

HTML Attributes

• alt = normal character data
  Gives the fallback content for the image.
  The requirements on the alt attribute's value are described in the next section.

• src = URL potentially surrounded by spaces
  Specifies a URL referencing a non-interactive, optionally animated, image that is neither paged nor scripted.

• usemap = hash-name reference
  Specifies a hash-name reference to a map element with which to associate the object.

• ismap = boolean
  Specifies that its img element provides access to a server-side image map.

• width = non-negative integer
  Give the width of the visual content of the element, in CSS pixels.

• height = non-negative integer
  Give the height of the visual content of the element, in CSS pixels.

See also global attributes.

Requirements for providing text to act as an alternative for images

A link or button containing nothing but the image

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

A phrase or paragraph with an alternative graphical representation

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.

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.png" alt="The network
passes data to the Tokenizer stage, which passes data 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>

A short phrase or label with an alternative graphical representation

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.

• 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="w3c.png" alt="W3C"></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>W3C<img src="w3c.png" alt=""> was ...</p>
</article>

• 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="w3c.png" alt=""></p></aside>

• 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="w3c.png" alt="It is written W3C by a white character, and the background is blue."></p>

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.

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

A graphical representation of some of the surrounding text

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.

A purely decorative image that doesn't add any information

In general, 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.

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

When a picture has been sliced into smaller image files that are then displayed together to form the complete picture again, 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 W3C has been split into two pieces, the first containing the letters "W3" and the second with the word "C". The alternative text ("W3C") is all in the first image.

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

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

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.

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

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.

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

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

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

• 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 himself know what the images represent (e.g. a blind photographer sharing an image on his blog).
  In such cases, the alt attribute may be omitted, but one of the following conditions must be met as well:
  • The title attribute is present and has a non-empty value.
  • The img element is in a figure element that contains a figcaption element that contains content other than inter-element whitespace, and, ignoring the figcaption element and its descendants, the figure element has no text node descendants other than inter-element whitespace, and no embedded content descendant other than the img element.

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.

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

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 it is strongly recommended that alternative text be included (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.

Example

Example A

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.

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

<!-- do not copy this example, it is an example of bad usage! -->
<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>

HTML Reference

The HTML5 specification defines the <img> element in 4.8.1 The img element.