HTML / Element

How to Use the source Element

The source element tells the browser, “Here is a file you can choose under these conditions.” It can offer image choices or audio and video files. The source element does not display or play anything by itself.

The answer first

The correct attributes depend on the parent element. For images, put source inside picture, use srcset, and finish with an img. For audio or video, put source inside audio or video and use src.

If you have only one image or media file, start with src on img, audio, or video. Use source when the browser needs to choose among candidates.

Choose an image candidate

picture groups image candidates. The final img displays the image and carries its text alternative in alt.

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

When the viewport matches the condition, the source image becomes a candidate. If no source matches, the image on img is available. Use srcset on the image source and put src and alt on img.

Choose audio or video resources

Inside audio or video, you can list more than one media file with source. The type attribute gives the browser a MIME type for each file.

<video controls width="640" height="360">
  <source src="/media/lesson.webm" type="video/webm">
  <source src="/media/lesson.mp4" type="video/mp4">
  <track kind="captions" src="/media/lesson.en.vtt"
         srclang="en" label="English captions">
</video>

The browser considers the candidate types and its playback capabilities. A type value is a format hint; it does not prove that the file is valid or can actually be played. Support can differ by format and codec.

Images and media use different attributes

Parent	Attributes on `source`	What completes the job?
`picture`	`srcset`, and as needed `media`, `type`, or `sizes`	`img` displays the image and carries its `alt` text
`audio` or `video`	`src`, and as needed `type` or `media`	The parent element plays the media

Do not use src on a source inside picture; image candidates use srcset. In a media element, use src; the image-specific srcset and sizes attributes do not belong there.

What do `media` and `type` do?

media describes an environment such as a viewport width or orientation.
type identifies an image or media format so unsupported candidates can be skipped.
srcset and sizes describe image candidates inside picture.

When several candidates match, their order can affect the choice. Adding a candidate does not mean every browser or device will choose the same file.

Common mistakes

Leaving out the final img and expecting source to display an image.
Using src on an image source in picture. Use srcset there.
Using srcset on a media source in audio or video. Use src there.
Putting image text on source. Put alt on img.
Assuming a type value makes a broken file playable.
Assuming child source elements provide the candidate list while audio or video has its own src.

Check it in Atlas

For the parent-specific attribute rules, image and media selection algorithms, candidate order, DOM API, and specification and implementation evidence, see source in Yugien Atlas. For images, continue with picture and img; for playback, see audio and video.