HTML / Element

How to Use the picture Element

The HTML picture element is a container for choosing an image resource based on conditions such as display size or image format. The final img element is what displays the image.

The answer first

Put any source elements first and always put an img element last inside picture. The browser checks matching sources and uses the img image when no source matches.

For candidates that differ only by resolution or display density, start with srcset and sizes on img. Use picture when the crop, format, or other source condition needs to change.

Minimal example

<picture>
  <source media="(min-width: 48rem)" srcset="/images/hero-wide.jpg">
  <img src="/images/hero-narrow.jpg"
       alt="A mountain and lake at sunset"
       width="640"
       height="360">
</picture>

Write the candidate and its condition on source, and write the final image and its alt text on img. The picture element itself does not display an image.

See it in a working example

A sample illustration of mountains and a lake

At a wide viewport the source candidate can be selected; otherwise the img candidate is available as the fallback. Resize the browser window to compare the conditions.

Choosing source conditions

Attribute	Main purpose
`media`	Switch images for viewport width, orientation, color scheme, or another media condition
`type`	Describe an image format so unsupported candidates can be skipped
`srcset` and `sizes`	Choose among candidates for the selected source based on slot size and pixel density

When several source elements are present, check both their conditions and their order. A source that matches earlier can prevent a later source from being considered.

picture or img?

Goal	Typical choice
Display one image	`img src`
Choose different resolutions of the same composition	`img srcset sizes`
Change the crop or composition by viewport	`picture source media` plus `img`
Choose an image format that the browser supports	`picture source type` plus `img`

Put alt text on img

Do not put alt on picture or source. Put the alternative text on the final img. For a decorative image, use alt="" and do not make assistive technology infer meaning from a visual choice alone.

Common mistakes

Leaving out img and expecting picture to display an image by itself.
Putting alt on source or picture and omitting it from img.
Adding complicated media conditions when img srcset sizes would solve a resolution-only problem.
Adding an image format candidate without checking its fallback and actual browser support.
Changing the image while failing to provide an alt and surrounding explanation that work for every candidate.

Check it in Atlas

For the picture content model, source selection, media, type, srcset, and sizes, the img fallback, accessibility, and implementation evidence, see picture in Yugien Atlas. See the source guide and source in Atlas for parent-specific source attributes; the related image candidate model is also covered by img in Atlas.