img element

If you don't know what an element is or how you must use it, I recommend you read the "HTML tags and attributes" tutorial that you can find in the HTML tutorials section.

Table of contents

Description

The img element represents an image, which is an external resource that can embedded in the body of a document. The location of this external resource must be specified in the src attribute.

The img element shouldn't be used to insert images without a meaning to the document. Typical examples of this misuse include images used as spacehoders or as layout tools.

HTML5 introduced the srcset attribute for this element, which is thought to provide different versiones of an image for different display needs (screen sizes, resolutions and pixel densities). Being it fairly new, browser support is very poor.

The alt attribute

Images are visual elements. This is one of the reasons of the existence of the alt attribute, which is thought to provide an alternate version of the image's content or purpose for those situations where they can't be properly accessed (visually impaired users, non-supporting browsers, configurations where images are disabled, etc.)

The alt attribute must provide an alternate version of the image by fulfilling with text the same image's purpose. A description of the image contents isn't always the best approach.

To make it clearer, we're going to explore the different uses of one same image and the most proper implementation of the alt attribute in each scenario. The image corresponds to the flag of Dominica.

First we're going to use it as an icon that will accompany the name of the country in a sentence. In this case, the alt attribute is irrelevant, as the presence of the flag is complementary only. The meaning of the text in this sentece wouldn't be altered with the removal of the image.

Example

<p>Charles Angelo Savarin is a politician from <img src="/assets/images/dominica-flag-icon.gif" alt=""> Dominica who has been President of Dominica since 2013. He is a member of the Dominica Labour Party and served for a time as Minister for National Security, Immigration, Labour and the Public Service.</p>

Charles Angelo Savarin is a politician from Dominica who has been President of Dominica since 2013. He is a member of the Dominica Labour Party and served for a time as Minister for National Security, Immigration, Labour and the Public Service.

Now we're making a very similar use of the flag. But this time, it's representing the country it belongs to, so it would be proper to provide the name of the country in the alt attribute. A good way of analyzing this situation would be to imagine this piece of document with the image replaced by the alt text. That way it's clear what's the purpose of the image and what the proper alternate text should be.

Example

<ul>
  <li>Name: Charles Angelo Savarin</li>
  <li>Year of birth: 1943</li>
  <li>Nationaly: <img src="/assets/images/dominica-flag-icon.gif" alt="Dominica"></li>
</ul>
  • Name: Charles Angelo Savarin
  • Year of birth: 1943
  • Nationaly: Dominica

The following case is a little different form the other two. Here, the main subject of the document is the flag of Dominica, and after the flag has been displayed, the author makes some comments about it.

It's easy to see how a user without the means to view the image would be in a disadvantage here. That's why the author has properly filled the image's alt attribute with a description of the flags's composition.

Example

<p>The flag of Dominica was adopted on November 3, 1978.</p>
<p><img src="/assets/images/dominica-flag.gif" alt="Dominica's flag has a green background and three lines (one yellow, one black and the other white) crossing its center from left to right, and again from top to bottom. In the center, there's a red circle with ten green stars on its border and a sisserou parrot in the middle."></p>
<p>Its parrot, endemic to Dominica, is an endangered species with a population of only 250-350 individuals.</p>

The flag of Dominica was adopted on November 3, 1978.

Dominica's flag has a green background and three lines (one yellow, one black and the other white) crossing its center from left to right, and again from top to bottom. In the center, there's a red circle with ten green stars on its border and a sisserou parrot in the middle.

Its parrot, endemic to Dominica, is an endangered species with a population of only 250-350 individuals.

In a similar way, the next piece of document describes the flag of Dominica, this time directly in the text. So, the author has just left the alt attribute empty, considering that it would be redundant to provide a description in such scenario.

Example

<p>The flag of Dominica was adopted on November 3, 1978.</p>
<p><img src="/assets/images/dominica-flag.gif" alt=""></p>
<p>Dominica's flag has a green background and three lines (one yellow, one black and the other white) crossing its center from left to right, and again from top to bottom. In the center, there's a red circle with ten green stars on its border and a sisserou parrot in the middle.</p>

The flag of Dominica was adopted on November 3, 1978.

Dominica's flag has a green background and three lines (one yellow, one black and the other white) crossing its center from left to right, and again from top to bottom. In the center, there's a red circle with ten green stars on its border and a sisserou parrot in the middle.

With these examples, you should have a clue about the purpose and proper use of the alt attribute. In any case, try to imagine what the document would look like if the image was replaced by its alternative text and you'll have an idea of what to put inside alt.

Examples

This example shows the img element in action, in its most basic way. The element is defined with its required attribute src, holding a URL pointing to the location of the image resource.

<img src="/assets/images/charles-darwin.jpg">

In our second example we'll try out the alt attribute. Here, a picture of Charles Darwin will be inserted in a piece of document to lift its image and accompany the textual information. The content of the alt attribute will provide, in this case, the name of the person depicted in the image and other information relevant in understanding its relationship with the contents of the article. This way, the alt attribute will be fulfilling its purpose, by providing a textual alternative to the image in the context it's been inserted.

Additionally, to improve presentation, the image is being floated to the right margin with a couple of style declarations.

<h1>Natural selection</h1>
<img src="/assets/images/charles-darwin.jpg" style="float: right; margin: 0 0 1em 2em" alt="Charles Darwin, Father of the theory of evolution by natural selection">
<p>Natural selection is the differential survival and reproduction of individuals due to differences in phenotype; it is a key mechanism of evolution. The term "natural selection" was popularised by Charles Darwin, who intended it to be compared with artificial selection, now more commonly referred to as selective breeding.</p>
<p>Variation exists within all populations of organisms. This occurs partly because random mutations arise in the genome of an individual organism, and these mutations can be passed to offspring. Throughout the individuals’ lives, their genomes interact with their environments to cause variations in traits.</p>

Natural selection

Charles Darwin, Father of the theory of evolution by natural selection

Natural selection is the differential survival and reproduction of individuals due to differences in phenotype; it is a key mechanism of evolution. The term "natural selection" was popularised by Charles Darwin, who intended it to be compared with artificial selection, now more commonly referred to as selective breeding.

Variation exists within all populations of organisms. This occurs partly because random mutations arise in the genome of an individual organism, and these mutations can be passed to offspring. Throughout the individuals’ lives, their genomes interact with their environments to cause variations in traits.

Attributes

Specific attributes

alt

A run of text providing equivalent content for those situations where images can't be viewed (visually impaired users, non-supporting agents or browsers with images disabled). The properties that an alternative text should present are treated in the description of this element.

Example

<img src="/assets/images/charles-dickens.jpg" alt="Charles Dickens, the greatest novelist of the Victorian period">
Charles Dickens, the greatest novelist of the Victorian period

src

The URL of the image resource. This attribute is required as it points to the resource that will be actually embedded in the document.

Example

<img src="/assets/images/charles-dickens.jpg">

srcset

A list of image candidate strings separated from each other by commas (","). Each one of the elements in this list represent an alternative to the original image (specified in the src attribute), designded specifically for medias with a particular screen size or pixel density (for example, devices with reduced screens, like cellphones). An image candidate string must be composed by:

  1. Zero or more space characters (" ").
  2. The URL of the image resource.
  3. Zero or more space characters (" ").
  4. Optionally, one of the following:
    • A width descriptor with the following structure:
      1. A space character (" ").
      2. A non-negative integer representing the with of the resource.
      3. A lowercase letter W ("w").
    • A pixel density descriptor with the following structure:
      1. A space character (" ").
      2. A non-negative floating-point number representing the pixel density of the resource.
      3. A lowercase letter X ("x").

If one image candidate string has a width descriptor, then all image candidate strings must have the width descriptor specified. Moreover, the presence of a image candidate strings with a width descriptor implies that the presence of the sizes attribute is required.

There mustn't be two image candidate strings with the same descriptors in the element. An image candidate string with no descriptors is equivalent to an image candidate string with a "1x" pixel density descriptor.

This attribute has been recently introduced in HTML5. Authors are adviced to expect little browser support for its features.

This example isn't live because it isn't meant to work inside the layout of this website. It's use of viewport width (vw) percentages to set the image's width, would break the example frame.

Example

<img src="/assets/images/Lunar_map.jpg" srcset="/assets/images/Lunar_map_(large).jpg 640w, /assets/images/Lunar_map.jpg 300w, /assets/images/Lunar_map_(small).jpg 100w" sizes="(min-width: 75em) 25vw, (max-width: 20em) 80vw, 50vw">

sizes

A comma-separated list of valid source sizes. Each source size (with exception of the last one) must be composed by:

  1. Optionally:
    1. A media query condition indicating in which cases this size is to be applied.
    2. A space character (" ").
  2. The width the image will take in CSS units.

The last source size must only be composed by the width of the image in CSS units, and will be used by browser as the default.

Supporting browsers will pick among the images provided in the srcset attribute, the one that best fits in the configuration of the device where it must be shown in, taking into account the information in this attribute. This method has been designed to simplify the task of providing images in responsive layouts and relies on the browser to choose the most appropriate image to display under the current conditions.

This attribute can only be declared if the srcset attribute is present and has at least one image resource with a width descriptor.

This example isn't live because it isn't meant to work inside the layout of this website. It's use of viewport width (vw) percentages to set the image's width, would break the example frame.

Example

<img src="/assets/images/Lunar_map.jpg" srcset="/assets/images/Lunar_map_(large).jpg 640w, /assets/images/Lunar_map.jpg 300w, /assets/images/Lunar_map_(small).jpg 100w" sizes="(min-width: 75em) 25vw, (max-width: 20em) 80vw, 50vw">

crossorigin

An enumerated value indicating if the request made to the external server should present CORS credentials or not. This attribute is useful when embedding images located in other servers that support cross-origin access, to allow reusing them in a canvas. The two possible values are (case-insensitive):

  • anonymous: CORS requests for the element will have the "omit credentials" flag set.
  • use-credentials: CORS requests for the element won't have the "omit credentials" flag set.

Example

<img src="http://www.otherserver.com/images/shalom.png" crossorigin="use-credentials">

usemap

A hash-name reference to the map this image is associated with. This reference must be composed by a hash sign ("#") and a string matching the value of the name attribute in the associated map element.

Example

<map name="image-map-1">
  <area href="../../tutorials.html" alt="HTML tutorials" shape="circle" coords="67,73,47">
  <area href="../../tutorials.html" alt="HTML tutorials" shape="rect" coords="82,78,156,99">
</map>
<img src="/assets/images/image-map-1-en.png" usemap="#image-map-1" alt="Example image map">
HTML tutorials HTML tutorials Example image map

ismap

A boolean value indicating if the element represents a server-side image map. If it has the value "ismap" or the empty string (""), or by just being present, the element represents a server-side image map.

This attribute will have effect only the element is a descendant of an a element with the href attribute properly defined.

Example

<a href="processing.php">
<img src="/assets/images/server-side-navbar.png" ismap alt="Websites' navigation bar">
</a>

width

A number of pixels indicating the width that the image will take when embedded in the document.

There's no need to provide the real width of the image in this attribute. Howerver, specifiyng a different width may produce pixelated images (when bigger) or load periods longer than necessary (when smaller).

Example

<img src="emblem.png" width="450" height="250" alt="Organization's emblem">

height

A number of pixels indicating the height that the image will take when embedded in the document.

There's no need to provide the real height of the image in this attribute. Howerver, specifiyng a different height may produce pixelated images (when bigger) or load periods longer than necessary (when smaller).

Example

<img src="emblem.png" width="450" height="250" alt="Organization's emblem">

referrerpolicy

Sets the referrer policy used when processing the element's attributes, which involves what information is sent about the referrer in a request to another resource. It may contain any of the following values:

  • no-referrer: No information about the referrer is sent in all requests.
  • no-referrer-when-downgrade: A full URL is sent only in requests from a TLS-protected enviroment (HTTPS) to a potentially thrusworthy URL and from a not TLS-protected enviroment to anywhere.
  • same-origin: A full URL is sent only in requests made in the same origin.
  • origin: A URL composed by protocol, host and port is sent in all requests.
  • strict-origin: A URL composed by protocol, host and port is sent only in requests from a TLS-protected enviroment (HTTPS) to a potentially thrusworthy URL and from a not TLS-protected enviroment to anywhere.
  • origin-when-cross-origin: A full URL is sent in requests made in the same origin and a URL composed by protocol, host and port is sent in cross-origin requests.
  • strict-origin-when-cross-origin: A full URL is sent in requests made in the same origin and a URL composed by protocol, host and port is sent in cross-origin requests, only in requests from a TLS-protected enviroment (HTTPS) to a potentially thrusworthy URL and from a not TLS-protected enviroment to anywhere.
  • unsafe-url: A full URL is sent in all request.

Note: When the empty string is specified, the value no-referrer is assumed.

Example

<a rel="license" src="https://creativecommons.org/publicdomain/zero/1.0/" referrerpolicy="unsafe-url">This content belongs to the public domain</a>

decoding

A hint to help browsers decide which method to use when decoding this image. This attribute can take one of the three following values:

  • sync: the image should be synchronously decoded, for atomic presentation with other content.
  • async: the image should be asynchronously decoded, to avoid delaying presentation of other content.
  • auto: the decision is left to the browser. This is the default value.

Example

<img src="circuit.png" decoding="sync">
...
<img src="nikola-tesla.png" decoding="async">

loading

An enumerated value indicating when should the browser load this image. This attribute can take one of two values:

  • lazy: browsers should load this image once it intersects the viewport but without delaying the window's load event.
  • eager: browsers should load the image immediately. This is the default value.

Example

<img src="product-1-image.png" loading="lazy">

longdesc

The URL of a resource with a longer explanation of the image's content/purpose than the one provided in the alt attribute.

This attribute has become obsolete in HTML5 due to little implementation by both, authors and browsers. Its functionality can be replaced with aria attributes.

Example

<img src="../treasure-island-map.jpg" alt="The map offers a top-side view of the treasure island. The dig site is marked with an X in the south-west region." longdesc="detailed-description-treasure-island-map.html">

align

A value indicating how the element should be aligned with respect to its surroundings. There are five possible case-insensitive values:

  • top: the top side of the image is vertically aligned with the baseline.
  • middle: the image is vertically centered with respect to the baseline.
  • bottom: the bottom side of the image is vertically aligned with the baseline. This is the default value.
  • left: the image is floated to the left margin.
  • right: the image is floated to the right margin.

This attribute has become obsolete in HTML5 because of its presentational nature. Authors should replace it with style sheet declarations.

Example

<img src="picture.png" align="center">

border

A number of pixels specifiyng the width of the border the image will be presented with.

This attribute became obsolete in HTML5 for being merely presentational. Authors should replace it with style sheets.

Example

<img src="../icon-green.gif" border="3">

hspace

A number of pixels indicating the amount of white space to be placed at the left and right margins of the image.

This attribute has become invalid in HTML5 for having only presentational purposes. Authors should replace it with style sheets declarations.

Example

<img src="../jhon-doe-1.jpg" hspace="200">

vspace

A number of pixels indicating the amount of white space to be placed at the top and bottom margins of the image.

This attribute has become invalid in HTML5 for having only presentational purposes. Authors should replace it with style sheets declarations.

Example

<img src="../jhon-doe-2.jpg" vspace="50">

name

A name for the element.

This attribute has become invalid in HTML5 for having only presentational purposes. Authors should replace it with style sheets declarations.

Example

<img src="../icon-green.gif" name="icon1">

Global attributes

For information about global attributes refer to this list of global attributes in HTML5.

Events

Global events

For information about global events refer to this list of global events in HTML5.