Skip to content
Tutorials Center
My learning

Topics

HTML Reference ยท Images and Media

The <img> element

Reference for the HTML <img> element: every attribute (alt, src, srcset, sizes, width, height, loading, decoding, fetchpriority and more) with examples and rules.

The <img> element embeds an image in the page: a photo, an illustration, a chart or a logo. src says which file to load and alt gives a text alternative that replaces the image for people who can't see it, for search engines and when the file fails to load.

<img> is a void element (no end tag). It is also a replaced element: the browser swaps the tag for the picture, which flows inline with the text around it unless CSS says otherwise.

HTML
<img src="/images/lighthouse.jpg" alt="A red lighthouse on a rocky point at dusk"
     width="800" height="533">

Try it

The basics: src, alt, width and height
Responsive images with srcset and sizes

The w numbers tell the browser how wide each file really is; sizes tells it how wide the image will be displayed. With both, it multiplies by the screen's pixel density and downloads the smallest file that is sharp enough. Once a larger file is cached, a browser may keep using it even when the preview shrinks.

Attributes

Attribute Values Description
alt Text, or empty The text alternative. Describe what the image conveys in this context. Use alt="" for purely decorative images so assistive technology skips them. Required in almost every case.
src URL The image file. Required, and must not be empty. Also the fallback when srcset is not understood.
srcset Comma-separated list of URL width (400w) or URL density (2x) Alternative files of the same picture. The browser chooses one based on screen density and, with w descriptors, on sizes. Don't mix w and x descriptors in one list.
sizes Comma-separated (media condition) length pairs, ending with a default length; or auto How wide the image will be shown, so the browser can pick from a w-based srcset before the layout is known. Required when srcset uses w. auto (only with loading="lazy") lets the browser use the laid-out width; it is newer and not yet supported everywhere.
width Non-negative integer The intrinsic width in CSS pixels. With height, it lets the browser reserve space before the file arrives, preventing layout shift.
height Non-negative integer The intrinsic height in CSS pixels. See width.
loading eager (default), lazy lazy defers loading until the image is near the viewport. Use it for images below the fold, never for the main image at the top of the page.
decoding auto (default), async, sync A hint about decoding the image: async lets other content render first; sync asks to show it together with the surrounding content.
fetchpriority auto (default), high, low The relative priority of the download. Use high for the largest above-the-fold image (often the Largest Contentful Paint element), low for less important ones.
crossorigin anonymous, use-credentials Fetch the image with CORS. Needed to read its pixels in a <canvas> when it comes from another origin.
referrerpolicy no-referrer, origin, same-origin, strict-origin-when-cross-origin, โ€ฆ How much referrer information to send with the request.
usemap # + a map name Connects the image to an image map: usemap="#plan" uses <map name="plan">.
ismap Boolean Server-side image map: when the image is inside a link, the click coordinates are appended to the URL (?x,y). Only allowed inside an <a> with href. Rarely used today.
elementtiming Identifier string Registers the image with the Element Timing API, so scripts can measure when it was painted. Defined in a separate specification (WICG), not in HTML; supported in Chromium browsers only.

It also accepts the global attributes and the onload and onerror event attributes. The old presentational attributes align, border, hspace, vspace, plus longdesc, lowsrc and name, are obsolete; use CSS and nearby text instead.

Usage notes

  • Writing good alt text. Say what matters about the picture here. A product photo needs its key details; an icon inside a button needs the button's action ("Search"), not a description of a magnifying glass. Don't start with "Image of"; screen readers already say it is an image.
  • Empty vs. missing alt. alt="" means "decorative, skip it". Leaving alt out means "unknown", and many screen readers then read the file name aloud. Always write the attribute.
  • Always set width and height. Use the file's real dimensions, then let CSS scale it (max-width: 100%; height: auto). The browser uses the ratio to reserve space, so text doesn't jump when the image loads.
  • Lazy loading. loading="lazy" saves bandwidth for images far down the page. On the main image above the fold it delays the most visible content, which hurts loading metrics.
  • Art direction. srcset only offers different sizes of the same picture. To show a different crop or format depending on the screen, wrap the image in <picture> with <source> elements.
  • Captions. To give an image a visible caption, put it in a <figure> with a <figcaption>. A caption does not replace alt.
  • Formats. JPEG for photos, PNG for screenshots and sharp edges, SVG for logos and diagrams, WebP and AVIF for smaller files. Offer a fallback with <picture> when you use a newer format.
  • Text in images. Avoid putting important text inside an image: it can't be resized, translated or searched. If you must, repeat the text in alt.

Technical summary

Content categories Flow content, phrasing content, embedded content, form-associated element, palpable content; with usemap: interactive content
Permitted content Nothing; it is a void element
Tag omission Start tag required; must not have an end tag
Permitted parents Any element that accepts embedded content
Implicit ARIA role img when alt is non-empty or missing; presentation (none) when alt=""
DOM interface HTMLImageElement
Default display inline (a replaced element)

Browser support

Supported in every browser. loading, decoding and fetchpriority are supported in all current browsers; sizes="auto" and elementtiming are not yet available everywhere and are safely ignored where unsupported.