Skip to content

Commit

Permalink
docs(fix): Improve <source> element page for consistency and clarity (
Browse files Browse the repository at this point in the history 
#29946)

* edits for consistency and clarity

* fixes review comments

* updates default values

---------

Co-authored-by: Chris Mills <[email protected]>
  • Loading branch information
@dipikabh @chrisdavidmills
dipikabh and chrisdavidmills committed Nov 8, 2023
1 parent 49208f4 commit 8681d02
Showing 1 changed file with 41 additions and 37 deletions.
78 changes: 41 additions & 37 deletions files/en-us/web/html/element/source/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ browser-compat: html.elements.source

{{HTMLSidebar}}

The **`<source>`** [HTML](/en-US/docs/Web/HTML) element specifies multiple media resources for the {{HTMLElement("picture")}}, the {{HTMLElement("audio")}} element, or the {{HTMLElement("video")}} element. It is a {{glossary("void element")}}, meaning that it has no content and does not have a closing tag. It is commonly used to offer the same media content in multiple file formats in order to provide compatibility with a broad range of browsers given their differing support for [image file formats](/en-US/docs/Web/Media/Formats/Image_types) and [media file formats](/en-US/docs/Web/Media/Formats).
The **`<source>`** [HTML](/en-US/docs/Web/HTML) element specifies one or more media resources for the {{HTMLElement("picture")}}, {{HTMLElement("audio")}}, and {{HTMLElement("video")}} elements. It is a {{glossary("void element")}}, which means that it has no content and does not require a closing tag. This element is commonly used to offer the same media content in multiple file formats in order to provide compatibility with a broad range of browsers given their differing support for [image file formats](/en-US/docs/Web/Media/Formats/Image_types) and [media file formats](/en-US/docs/Web/Media/Formats).

{{EmbedInteractiveExample("pages/tabbed/source.html", "tabbed-standard")}}

Expand Down Expand Up @@ -67,67 +67,71 @@ The **`<source>`** [HTML](/en-US/docs/Web/HTML) element specifies multiple media

## Attributes

This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes).
This element supports all [global attributes](/en-US/docs/Web/HTML/Global_attributes). In addition, the following attributes can be used with it:

- `type`

- : The [MIME media type of the image](/en-US/docs/Web/Media/Formats/Image_types) or [other media type](/en-US/docs/Web/Media/Formats/Containers), optionally with a [`codecs` parameter](/en-US/docs/Web/Media/Formats/codecs_parameter).
- : Specifies the [MIME media type of the image](/en-US/docs/Web/Media/Formats/Image_types) or [other media type](/en-US/docs/Web/Media/Formats/Containers), optionally including a [`codecs` parameter](/en-US/docs/Web/Media/Formats/codecs_parameter).

- `src`

- : Required if the `source` element's parent is an {{HTMLElement("audio")}} and {{HTMLElement("video")}} element, but not allowed if the `source` element's parent is a {{HTMLElement("picture")}} element.

Address of the media resource.
- : Specifies the URL of the media resource. Required if the parent of `<source>` is {{HTMLElement("audio")}} or {{HTMLElement("video")}}. Not allowed if the parent is {{HTMLElement("picture")}}.

- `srcset`

- : Required if the `source` element's parent is a {{HTMLElement("picture")}} element, but not allowed if the `source` element's parent is an {{HTMLElement("audio")}} or {{HTMLElement("video")}} element.
- : Specifies a comma-separated list of one or more image URLs and their descriptors. Required if the parent of `<source>` is {{HTMLElement("picture")}}. Not allowed if the parent is {{HTMLElement("audio")}} or {{HTMLElement("video")}}.

A list of one or more strings, separated by commas, indicating a set of possible images represented by the source for the browser to use. Each string is composed of:
The list consists of strings separated by commas, indicating a set of possible images for the browser to use. Each string is composed of:

1. One URL specifying an image.
2. A width descriptor, which consists of a string containing a positive integer directly followed by `"w"`, such as `300w`. The default value, if missing, is the infinity.
3. A pixel density descriptor, that is a positive floating number directly followed by `"x"`. The default value, if missing, is `1x`.
- A URL specifying an image location.
- An optional width descriptor—a positive integer directly followed by `"w"`, such as `300w`.
- An optional pixel density descriptor—a positive floating number directly followed by `"x"`, such as `2x`.

Each string in the list must have at least a width descriptor or a pixel density descriptor to be valid. The two types of descriptors should not be mixed together and only one should be used consistently throughout the list. Among the list, the value of each descriptor must be unique. The browser chooses the most adequate image to display at a given point of time. If the `sizes` attribute is present, then a width descriptor must be specified for each string. If the browser does not support `srcset`, then `src` will be used for the default source.
Each string in the list must have either a width descriptor or a pixel density descriptor to be valid. These two descriptors should not be used together; only one should be used consistently throughout the list. The value of each descriptor in the list must be unique. The browser chooses the most adequate image to display at a given point of time based on these descriptors. If the descriptors are not specified, the default value used is `1x`. If the `sizes` attribute is also present, then each string must include a width descriptor. If the browser does not support `srcset`, then `src` will be used for the default image source.

- `sizes`

- : Allowed if the `source` element's parent is a {{HTMLElement("picture")}} element, but not allowed if the `source` element's parent is an {{HTMLElement("audio")}} or {{HTMLElement("video")}} element.
- : Specifies a list of source sizes that describe the final rendered width of the image. Allowed if the parent of `<source>` is {{HTMLElement("picture")}}. Not allowed if the parent is {{HTMLElement("audio")}} or {{HTMLElement("video")}}.

A list of source sizes that describes the final rendered width of the image represented by the source. Each source size consists of a comma-separated list of media condition-length pairs. Before laying the page out, the browser uses this information to determine which image is defined in [`srcset`](#srcset) to use. Please note that `sizes` will have its effect only if width dimension descriptors are provided with `srcset` instead of pixel ratio values (200w instead of 2x for example).
The list consists of source sizes separated by commas. Each source size is media condition-length pair. Before laying the page out, the browser uses this information to determine which image defined in [`srcset`](#srcset) to display. Note that `sizes` will take effect only if width descriptors are provided with `srcset`, not pixel density descriptors (i.e., `200w` should be used instead of `2x`).

- `media`

- : [Media query](/en-US/docs/Web/CSS/CSS_media_queries) of the resource's intended media.
- : Specifies the [media query](/en-US/docs/Web/CSS/CSS_media_queries) for the resource's intended media.

- `height`

- : Allowed if the `source` element's parent is a {{HTMLElement("picture")}} element, but not allowed if the `source` element's parent is an {{HTMLElement("audio")}} or {{HTMLElement("video")}} element.
- : Specifies the intrinsic height of the image in pixels. Allowed if the parent of `<source>` is a {{HTMLElement("picture")}}. Not allowed if the parent is {{HTMLElement("audio")}} or {{HTMLElement("video")}}.

The intrinsic height of the image, in pixels. Must be an integer without a unit.
The height value must be an integer without any units.

- `width`

- : Allowed if the `source` element's parent is a {{HTMLElement("picture")}} element, but not allowed if the `source` element's parent is an {{HTMLElement("audio")}} or {{HTMLElement("video")}} element.

The intrinsic width of the image in pixels. Must be an integer without a unit.

If the `type` attribute isn't specified, the media's type is retrieved from the server and checked to see if the user agent can handle it; if it can't be rendered, the next `<source>` is checked. If the `type` attribute is specified, it's compared against the types the user agent can present, and if it's not recognized, the server doesn't even get queried; instead, the next `<source>` element is checked at once.
- : Specifies the intrinsic width of the image in pixels. Allowed if the parent of `<source>` is a {{HTMLElement("picture")}}. Not allowed if the parent is {{HTMLElement("audio")}} or {{HTMLElement("video")}}.

When used in the context of a `<picture>` element, the browser will fall back to using the image specified by the `<picture>` element's {{HTMLElement("img")}} child if it is unable to find a suitable image to use after examining every provided `<source>`.
The width value must be an integer without any units.

## Usage notes

The `<source>` element is a **{{glossary("void element")}}**, which means that it not only has no content but also has no closing tag. That is, you _never_ use "`</source>`" in your HTML.

For information about image formats supported by web browsers and guidance on selecting appropriate formats to use, see our [Image file type and format guide](/en-US/docs/Web/Media/Formats/Image_types) on the web. For details on the video and audio media types you can use, see the [Guide to media types formats used on the web](/en-US/docs/Web/Media/Formats).
The browser goes through a list of `<source>` elements to find a format it supports. It uses the first one it can display. For each `<source>` element:

- If the `type` attribute isn't specified, the browser retrieves the media's type from the server and determines if it can be displayed. If the media can't be rendered, the browser checks the next `<source>` in the list.
- If the `type` attribute is specified, the browser immediately compares it with the media types it can display. If the type is not supported, the browser skips querying the server and directly checks the next `<source>` element.

If none of the `<source>` elements provide a usable source:

- In the case of a `<picture>` element, the browser will fall back to using the image specified in the `<picture>` element's {{HTMLElement("img")}} child.
- In the case of an `<audio>` or `<video>` element, the browser will fall back to displaying the content included between the element's opening and closing tags.

For information about image formats supported by web browsers and guidance on selecting appropriate formats to use, see our [Image file type and format guide](/en-US/docs/Web/Media/Formats/Image_types). For details on the video and audio media types you can use, see the [Media type and format guide](/en-US/docs/Web/Media/Formats).

## Examples

### Video with type attribute example
### Using the `type` attribute with `<video>`

This example demonstrates how to offer a video in WebM format for users whose browsers support WebM format, Ogg format for users whose browsers support Ogg format, and a QuickTime format video for users whose browsers support that. If the `audio` or `video` element is not supported by the browser, a notice is displayed instead. If the browser supports the element but does not support any of the specified formats, an `error` event is raised and the default media controls (if enabled) will indicate an error. Be sure to reference our [guide to media types and formats on the web](/en-US/docs/Web/Media/Formats) for details on what media file formats you can use and how well they're supported by browsers.
This example demonstrates how to offer a video in different formats: WebM for browsers that support it, Ogg for those that support Ogg, and QuickTime for browsers that support QuickTime. If the `<audio>` or `<video>` element is not supported by the browser, a notice is displayed instead. If the browser supports the element but does not support any of the specified formats, an `error` event is raised and the default media controls (if enabled) will indicate an error. For more details on which media file formats to use and their browser support, refer to our [Media type and format guide](/en-US/docs/Web/Media/Formats).

```html
<video controls>
Expand All @@ -138,9 +142,9 @@ This example demonstrates how to offer a video in WebM format for users whose br
</video>
```

### Video with media attribute example
### Using the `media` attribute with `<video>`

This example demonstrates how to offer an alternate source file for viewports at or above a certain width. When a user's browsing environment meets the specified `media` condition, the associated `<source>` element is chosen, and the contents of its `src` attribute are requested and rendered. If the `media` condition does not match, the user agent will move on to the next `<source>` in the source order. The second source option in the below code has no `media` condition, so will be selected for all other browsing contexts.
This example demonstrates how to offer an alternate source file for viewports above a certain width. When a user's browsing environment meets the specified `media` condition, the associated `<source>` element is chosen. The contents of its `src` attribute are then requested and rendered. If the `media` condition does not match, the browser will move on to the next `<source>` in the list. The second `<source>` option in the code below has no `media` condition, so it will be selected for all other browsing contexts.

```html
<video controls>
Expand All @@ -150,11 +154,11 @@ This example demonstrates how to offer an alternate source file for viewports at
</video>
```

For more examples, the learning area article [Video and audio content](/en-US/docs/Learn/HTML/Multimedia_and_embedding/Video_and_audio_content) is a great resource.
For more examples, the [Video and audio content](/en-US/docs/Learn/HTML/Multimedia_and_embedding/Video_and_audio_content) article in the Learn area is a great resource.

### Picture example
### Using the `media` attribute with `<picture>`

In this example, two `<source>` elements are included within the {{HTMLElement("picture")}}, providing versions of an image to use when the available space exceeds certain widths. If the available width is less than the smallest of these widths, the user agent will fall back to the image given by the {{HTMLElement("img")}} element.
In this example, two `<source>` elements are included within {{HTMLElement("picture")}}, providing versions of an image to use when the available space exceeds certain widths. If the available width is less than the smallest of these widths, the browser will fall back to the image specified in the {{HTMLElement("img")}} element.

```html
<picture>
Expand All @@ -164,9 +168,9 @@ In this example, two `<source>` elements are included within the {{HTMLElement("
</picture>
```

With the `<picture>` element, you must always include an `<img>` with a fallback image, with an `alt` attribute to ensure accessibility (unless the image is an irrelevant background decorative image).
With the `<picture>` element, you must always include an `<img>` with a fallback image. Also, make sure to add an `alt` attribute for accessibility, unless the image is purely decorative and irrelevant to the content.

### Picture with height & width attributes example
### Using `height` and `width` attributes with `<picture>`

In this example, three `<source>` elements with `height` and `width` attributes are included in a {{HTMLElement("picture")}} element.
A [media query](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries) allows the browser to select an image to display with the `height` and `width` attributes based on the [viewport](/en-US/docs/Glossary/Viewport) size.
Expand Down Expand Up @@ -206,9 +210,9 @@ A [media query](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries) allow

## See also

- [Guide to media types and formats on the web](/en-US/docs/Web/Media/Formats)
- [Image file type and format guide](/en-US/docs/Web/Media/Formats/Image_types)
- {{HTMLElement("picture")}} element
- {{HTMLElement("audio")}} element
- {{HTMLElement("picture")}} element
- {{HTMLElement("video")}} element
- [Web Performance](/en-US/docs/Learn/Performance)
- [Image file type and format guide](/en-US/docs/Web/Media/Formats/Image_types)
- [Media type and format guide](/en-US/docs/Web/Media/Formats)
- [Web performance](/en-US/docs/Learn/Performance)

0 comments on commit 8681d02

Please sign in to comment.