The <img> Element

Technical Summary

Definition / Categories

Item	Specification summary
Meaning	Embedded content representing an image
Categories	Flow content, phrasing content, embedded content, form-associated element, and palpable content. Interactive content when usemap or controls is specified
Context	Where embedded content is expected
Content model	Empty; no child content
Tag omission	Neither the start tag nor the end tag is omissible
Content attributes	Global attributes; alt, src, srcset, sizes, crossorigin, usemap, ismap, controls, width, height, referrerpolicy, decoding, loading, and fetchpriority
DOM interface	HTMLImageElement

Image meaning and the alt boundary

In the HTML Standard, the image selected from src, srcset, or a source element under picture is the embedded content. The alt value is the alternative content for people who cannot process images or who have image loading disabled.

Case	Claim and review point
Informative image	Provide a concise alternative that communicates the important information instead of relying on surrounding visual context
Decorative image	Use alt="" to indicate that the image does not add content for assistive-technology users
Functional image	Describe the purpose of the link or operation; a description of the pixels alone may be insufficient
Image of text	Provide meaningful text in an equivalent textual form
Detailed image	Divide responsibility between short alt text and a longer explanation in surrounding content, a figure, or a caption

Do not infer importance only from whether the alt attribute is present. An empty value explicitly represents an image with no alternative text, and is not the same as omitting the attribute.

src, srcset, and sizes

Use src for a single resource. For responsive images, srcset lists candidate URLs with density or width descriptors. With width descriptors, sizes describes the expected width of the image slot.

<img
  src="/images/article-800.jpg"
  srcset="/images/article-400.jpg 400w,
          /images/article-800.jpg 800w,
          /images/article-1600.jpg 1600w"
  sizes="(max-width: 600px) 100vw, 800px"
  alt="A landscape illustrating the article"
  width="1600"
  height="900">

The user agent selects a candidate using conditions such as the display slot and pixel density. The HTML Standard's image-processing model then associates the selected source and pixel density with an image request. Therefore, srcset is not a directive to always use the largest or smallest file.

When the parent is picture, the user agent evaluates the source elements and their conditions before using the final img as the element's fallback and base. picture and source should be treated as separate specification boundaries.

Dimensions, replaced elements, and layout

An img is treated as a replaced element. When its image data is available, the paint source uses density-corrected natural dimensions. The width and height attributes provide a dimension attribute source for the visual content in CSS pixels.

In implementation, width and height values that preserve the image's aspect ratio let the browser predict the layout area before the image arrives. Do not treat attribute values, CSS sizes, natural dimensions, selected pixel density, and rendered dimensions as the same value.

Fetching, decoding, and events

Attribute or API	Review point
loading	A hint to defer image fetching; viewport distance and implementation conditions mean it is not an absolute fetching guarantee
decoding	A hint about image decoding; specified values and actual rendering order must be observed separately
fetchpriority	A hint about fetch priority; it does not alone determine the priority of the entire network
complete	An IDL observation about the current request; it does not alone mean that the image succeeded
naturalWidth / naturalHeight	Observation points for density-corrected natural dimensions
currentSrc	Observation point for the currently selected source URL
decode()	Promise-based API entry point for decoding the image before it is safely rendered

load and error events, current and pending requests, and image-data updates caused by DOM mutations are implementation states distinct from attribute strings. One observed load event does not describe every selection, fetching, or decoding step.

DOM Interface

const image = document.querySelector('img');

image.alt;
image.currentSrc;
image.srcset;
image.sizes;
image.naturalWidth;
image.naturalHeight;
image.complete;
await image.decode();

HTMLImageElement exposes IDL attributes that reflect content attributes as well as currentSrc, natural dimensions, and APIs for observing fetch and decoding state. Record attribute values, selected source, natural size, and rendered size separately.

Fact / Evidence

Normative meaning, alternative text, candidate selection, dimensions, fetch hints, DOM APIs, and accessibility mappings are recorded as claims with conditions and source locations. Browser fetching results and accessibility trees are separated into Implementation Evidence below.

Evidence

1. HTML Standard: The img element — meaning, categories, content model, alt, attributes, and HTMLImageElement
2. HTML Standard: Images — adaptive images, srcset, sizes, candidate selection, and image processing
3. HTML Standard: Dimension attributes — width and height as a dimension attribute source
4. HTML Accessibility API Mappings: img — img role, alt, accessible name, and none/presentation mapping entry points
5. Web Platform Tests: the-img-element — test entry point for img, responsive images, candidate selection, and attribute processing

Implementation Evidence

Browser behavior, WPT, and accessibility-tree observations are recorded separately from normative claims. img-v1 ran in Chrome 153 and Edge 153 / Windows NT 10.0, with all 12 checks passing in each environment. WPT, platform APIs, assistive technology, Firefox, and Safari remain open separately.

Fixture result: img-v1 checked alt presence and empty values, successful and failed src requests, currentSrc under srcset and sizes, width/height and natural dimensions, load / error, decode(), IDL reflection for loading, decoding, and fetchpriority, and Resource Timing. Chrome used 1920×855 at DPR 1; Edge used 762×699 at DPR 1.25.

Fetch timing, candidate selection, natural dimensions, rendering, accessibility trees, platform APIs, and assistive-technology output can depend on browser, OS, viewport, DPR, and network conditions. A single environment's observation is not registered as universal behavior.

Coverage / Open Issues

• ReviewedMeaning, categories, context, empty content model, main content attributes, and HTMLImageElement
• Reviewedalt as alternative content, informative/decorative/functional image roles, and the HTML-AAM img mapping entry point
• ReviewedEntry points for image candidate selection and image-request processing through srcset, sizes, and picture
• OpenFirefox and Safari, and multiple DPR/viewport/network conditions beyond the Chrome 153 and Edge 153 observations, for currentSrc, candidate selection, and load/error
• OpenActual fetching, decoding, rendering, and priority timing for loading, decoding, and fetchpriority
• OpenRemaining individual WPT runs beyond the selected four files with 9/9 pass, complete HTML-AAM mappings, accessibility trees, platform APIs, assistive technology, controls, and CORS/referrer policy

This is initial coverage. The Chrome 153 and Edge 153 fixture observations and the selected four WPT files with 9/9 pass are recorded, but remaining WPT coverage, partial AAM observations, assistive technology, and multi-environment behavior are not treated as full conformance evidence, and the entire img element has not been tested.

Related surface

For a beginner-friendly explanation of images, alt, responsive images, and dimensions, see the Yugien img element page. Image maps, where map, area, and usemap link places inside an image, have a dedicated image maps topic. The purpose and activation boundary when an image is a link are covered by the a element. The distinction from embedding another document as a content navigable is covered by the iframe element. For switching image candidates by display condition or format, see the picture element. The meaning of source inside audio/video and figure remain separate specification boundaries.

The bitmap and pixel-readback boundary after drawing an image with JavaScript is covered by the canvas element Topic.