source element

If you don't know what an element is or how you must use it, I recommend you read the "HTML tags and attributes" tutorial that you can find in the HTML tutorials section.

Description

The source element allows authors to provide different versions of a file in media elements (audio and video) and pictures (picture). A media element or picture can contain one or more source elements, each of which provides a different version of the media (encoded using a different codec) or picture (in different sizes or formats). Then, it's up to the browser to choose a source to be loaded, a decission it'll make based on the formats it supports and the dimensions of the picture (best fit).

Authors must choose one of the two ways to specify a media resource but never both. If you declare the src attribute in the media element (audio and video) you won't be able to provide alternatives with the source element.

Browser support for the picture element is very low. Authors may have to rely on media queries to achieve the same effect cross-browser, until support grows.

Examples

In the next example, we're providing an audio file in two different formats with the source element, allowing browsers to choose the version they are capable of supporting.

For browsers supporting the audio element, there's no need to provide more than two formats (MP3 and Ogg) to make our audio cross-browser.

<audio controls>
  <source src="../../audio/Jahzzar_The_Flowers_Are_Still_Standing.ogg" type="audio/ogg">
  <source src="../../audio/Jahzzar_The_Flowers_Are_Still_Standing.mp3" type="audio/mpeg">
</audio>

The audio corresponds to the song "The Flowers Are Still Standing" (Jahzzar) / CC BY-SA 4.0.

In our second example, we're inserting a video. Like in the previous case, the source element is helping us to provide more than one format, thus allowing browsers to choose the version they support better.

For browsers supporting the video element, there's no need to serve more than two formats (MP4 and Ogg) to make our audio cross-browser. Nevertheless, we're going to make available a third version, WebM, for being the best candidate to act as the web's video standard in the near future.

To improve compatibility even further, we'll place the MP4 version first to avoid a particular bug in iPad.

<video width="384" height="288" controls>
  <source src="../../videos/A_Flight_To_Mars.mp4" type="video/mp4">
  <source src="../../videos/A_Flight_To_Mars.webm" type="video/webm">
  <source src="../../videos/A_Flight_To_Mars.ogg" type="video/ogg">
</video>

Now, the pictureelement is used to give a couple of versions of the same image in different sizes. Here the srcset attribute becomes essential in order to provide the image resource, while the media attribute defines in which situations each source element should be used.

Browser support for the picture element is very low. Authors may have to rely on scripts to achieve the same effect cross-browser, until support grows.

<picture>
  <source media="(min-width: 1280px)" srcset="../../images/charles-darwin-l.jpg">
  <source media="(max-width: 520px)" srcset="../../charles-darwin-s.jpg">
  <img class="flr" src="../../images/charles-darwin.jpg" alt="Charles Robert Darwin">
</picture>
<p>Charles Robert Darwin was an English naturalist and geologist, best known for his contributions to evolutionary theory. He established that all species of life have descended over time from common ancestors, and in a joint publication with Alfred Russel Wallace introduced his scientific theory that this branching pattern of evolution resulted from a process that he called natural selection.</p>
<p>Darwin published his theory of evolution with compelling evidence in his 1859 book On the Origin of Species, overcoming scientific rejection of earlier concepts of transmutation of species. By the 1870s the scientific community and much of the general public had accepted evolution as a fact.</p>
Charles Robert Darwin

Charles Robert Darwin was an English naturalist and geologist, best known for his contributions to evolutionary theory. He established that all species of life have descended over time from common ancestors, and in a joint publication with Alfred Russel Wallace introduced his scientific theory that this branching pattern of evolution resulted from a process that he called natural selection.

Darwin published his theory of evolution with compelling evidence in his 1859 book On the Origin of Species, overcoming scientific rejection of earlier concepts of transmutation of species. By the 1870s the scientific community and much of the general public had accepted evolution as a fact.

Lastly, we'll be providing a picture in two different formats: the new WebP, which has little support among browsers, and the traditional PNG that's supported almost everywhere. By providing the image with the new format in a source and the fallback in img we're allowing supporting browsers to use WebP, while letting non-supporting browsers to safely display the well known PNG version.

<picture>
  <source type="image/webp" srcset="../../images/camera.webp">
  <img src="../../images/camera.png" alt="Photographic camera schematics">
</picture>
Photographic camera schematics

Attributes

Specific attributes

src

The URI (location) of the media resource (audio or video) this element is providing.

This attribute can only be declared in a source element that is child of a media element (audio or video).

Example

<audio controls>
  <source src="../../audio/Jahzzar_Please_Listen_Carefully.ogg" type="audio/ogg">
  <source src="../../audio/Jahzzar_Please_Listen_Carefully.mp3" type="audio/mpeg">
</audio>

The audio corresponds to the song "Please Listen Carefully" (Jahzzar) / CC BY-SA 4.0.

type

The content type (or Internet media type) that the resource provided by the element is expected to have. In case of media elements, authors can also specify the codecs necessaries to correctly handle the file, appending after the type:

  1. A semicolon (";").
  2. Any number of space characters.
  3. The word "codecs".
  4. An equal sign ("=").
  5. The codecs information. If this information contains space characters, it must be enclosed by quotes or double quotes. Quotation must differ from that used for the attribute's content.

The content of this attribute gives browsers with a hint about the type of resource the element is providing. This can help them in deciding which resource to load before fetching it.

Example

<audio controls>
  <source src="../../audio/Jahzzar_Sketch_Rum_Portrait.ogg" type="audio/ogg; codecs='vorbis'">
  <source src="../../audio/Jahzzar_Sketch_Rum_Portrait.mp3" type="audio/mpeg">
</audio>

The audio corresponds to the song "Sketch (rum-portrait)" (Jahzzar) / CC BY-SA 3.0.

srcset

A list of image candidate strings separated from each other by commas (","). Each one of the elements in this list represent an alternative to the original image, designded specifically for medias with a particular screen size or pixel density (for example, devices with reduced screens, like cellphones). An image candidate string must be composed by:

  1. Zero or more space characters (" ").
  2. The URL of the image resource.
  3. Zero or more space characters (" ").
  4. Optionally, one of the following:
    • A width descriptor with the following structure:
      1. A space character (" ").
      2. A non-negative integer representing the with of the resource.
      3. A lowercase letter W ("w").
    • A pixel density descriptor with the following structure:
      1. A space character (" ").
      2. A non-negative floating-point number representing the pixel density of the resource.
      3. A lowercase letter X ("x").

If one image candidate string has a width descriptor, then all image candidate strings must have the width descriptor specified. Moreover, the presence of a image candidate strings with a width descriptor implies that the presence of the sizes attribute is required.

There mustn't be two image candidate strings with the same descriptors in the element. An image candidate string with no descriptors is equivalent to an image candidate string with a "1x" pixel density descriptor.

This attribute can only be declared in a source element that is child of a picture element. In such cases, its presence is mandatory.

This attribute has been recently introduced in HTML5. Authors are adviced to expect little browser support for its features.

Example

<picture>
  <source media="(min-width: 1024px)" srcset="../../images/Lunar_map_(large).jpg">
  <img src="../../images/Lunar_map.jpg" alt="First map of the moon made by Thomas Harriot in 1609">
</picture>
First map of the moon made by Thomas Harriot in 1609

sizes

A comma-separated list of valid source sizes. Each source size (with exception of the last one) must be composed by:

  1. Optionally:
    1. A media query condition indicating in which cases this size is to be applied.
    2. A space character (" ").
  2. The width the image will take in CSS units.

The last source size must only be composed by the width of the image in CSS units, and will be used by browser as the default.

Supporting browsers will pick among the images provided in the srcset attribute, the one that best fits in the configuration of the device where it must be shown in, taking into account the information in this attribute. This method has been designed to simplify the task of providing images in responsive layouts and relies on the browser to choose the most appropriate image to display under the current conditions.

This attribute can only be declared if the srcset attribute is present and has at least one image resource with a width descriptor.

This example isn't live because it isn't meant to work inside the layout of this website. It's use of viewport width (vw) percentages to set the image's width, would break the example frame.

Example

<picture>
  <source srcset="../../images/Lunar_map_(large).jpg 640w, ../../images/Lunar_map.jpg 300w, ../../images/Lunar_map_(small).jpg 100w" sizes="(min-width: 75em) 25vw, (max-width: 20em) 80vw, 50vw">
  <img src="../../images/Lunar_map.jpg" alt="First map of the moon made by Thomas Harriot in 1609">
</picture>

media

A media query condition that the device configuration will need to satisfy for the image resource provided by this element to be used.

This attribute can only be declared in a source element that is child of a picture element. It's use with media elements is invalid.

Example

<picture>
  <source media="(min-width: 640px)" srcset="../../images/Lunar_map_(large).jpg">
  <source media="(max-width: 100px)" srcset="../../images/Lunar_map_(small).jpg">
  <img src="../../images/Lunar_map.jpg" alt="First map of the moon made by Thomas Harriot in 1609">
</picture>
First map of the moon made by Thomas Harriot in 1609

Global attributes

For information about global attributes refer to this list of global attributes in HTML5.

Events

Global events

For information about global events refer to this list of global events in HTML5.