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.
<img src="/images/lighthouse.jpg" alt="A red lighthouse on a rocky point at dusk" width="800" height="533">
Try it
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
alttext. 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". Leavingaltout means "unknown", and many screen readers then read the file name aloud. Always write the attribute. - Always set
widthandheight. 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.
srcsetonly 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 replacealt. - 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.
Related
<picture>โ art direction and format fallbacks<source>โ alternative image sources inside<picture><map>and<area>โ clickable regions<figure>โ an image with a caption<svg>โ vector graphics written inline- Lesson: Images
- Lesson: Responsive Images
- Lesson: Image Maps
- Lesson: Figures
- Lesson: Performance