HTML img element

Reference for the HTML img element: void content model, meaningful versus empty decorative alt, width and height, and loading=lazy.

标签页正文目前为英文。

The img element embeds an image. It is a void element: no end tag and no children. src (or srcset) provides the image resource. alt is not optional as a decision: every img needs an alt attribute, which may be a text equivalent or, for decorative images, an empty string.

This page deepens the catalog card for <img>. The file names in the examples are local documentation paths. This site build does not fetch those files, and the checker does not load image bytes.

Official sources: MDN <img> element and the WHATWG HTML Living Standard. Fragments were checked with Python 3.13 html.parser. That parser builds an element tree; it is not a WHATWG conformance checker, and this is not a browser or accessibility test.

HTML tag catalog → · HTML tutorial overview →

Void element and the alt decision

If the image conveys information that is not already in nearby text, alt should be a functional equivalent, written as if the image were not there. Do not start with "image of" unless that phrasing is itself useful. If the image is purely decorative, use alt="" so assistive technology can ignore it.

A missing alt attribute is not the same as alt="". Missing alt means the alternative text is unknown; user agents and assistive technologies may fall back to a file name or a generic image announcement. That is not a decorative image. The first example has one informative image in a figure and one decorative divider with an empty alt.

Meaningful alt and decorative alt=""

<img src alt width height>
<img src alt="" width height>

Provide a text equivalent, or use an empty alt for a decorative image. Do not omit the attribute.

AttributeDescription
srcURL of the image resource. The examples use local documentation file names and are not fetched here.
altRequired as a decision. A non-empty string is a text equivalent. alt="" marks a decorative image. Omitting alt is not equivalent to alt="".
srcset, sizesOptional candidates and size hints for responsive images. Not required for the examples on this page.
  • This is a markup rule, not a measured screen-reader announcement.
html
<figure>
  <img src="garden.jpg" alt="A raised garden bed with labeled herb rows" width="640" height="360">
  <figcaption>Spring planting layout</figcaption>
</figure>
<img src="divider.svg" alt="" width="120" height="8">

What this markup means

The photograph has a short text equivalent because the picture itself carries information. The divider is decorative, so alt is present and empty. Neither path is loaded by the documentation checker.

Related: Tag catalog: <img>, HTML tutorial: Practice

MDN documentation → · WHATWG HTML Standard →

width, height, and loading="lazy"

The width and height attributes give the image's intrinsic dimensions in CSS pixels. They help the user agent reserve an aspect ratio before the file loads, which can reduce layout shift. They do not crop the image by themselves; CSS can still change the rendered size.

loading="lazy" is a hint to defer loading until the image is near the viewport. The default is eager. Lazy loading is useful for images well below the first screen. It is a poor default for the primary image at the top of a page (often the largest contentful paint candidate), because deferring that file can delay rendering. This page did not measure loading performance in a browser.

Reserved dimensions and a lazy-loaded image

<img src alt width height>
<img src alt width height loading="lazy">

width and height reserve an aspect ratio. loading="lazy" defers off-screen images. The default loading is eager.

AttributeDescription
widthUnsigned width in CSS pixels. Together with height, it can reserve aspect ratio.
heightUnsigned height in CSS pixels.
loadingeager (default) or lazy. lazy is a hint, not a guarantee, and is not a substitute for choosing a reasonable image file.
decodingOptional hint (sync, async, or auto) for when to decode the image. Not demonstrated here.
  • The first image is left eager on purpose. The second uses loading="lazy" as an off-screen example.
html
<img
  src="hero.jpg"
  alt="Close-up of tomato seedlings in a tray"
  width="800"
  height="450"
>
<img
  src="tools.jpg"
  alt="Hand tools hanging on a shed wall"
  width="400"
  height="300"
  loading="lazy"
>

What this markup means

Both images have a non-empty alt and explicit width and height. Only the second sets loading="lazy". No image bytes are requested by this documentation page.

Related: Tag catalog: <img>

MDN documentation → · WHATWG HTML Standard →