HTML
Living Standard — Last Updated 1 November 2024
Living Standard — Last Updated 1 November 2024
picture elementSupport in all current engines.
HTML element. It doesn't implement specific properties or methods.">HTMLPictureElement
Support in all current engines.
source elements, followed by one img element,
optionally intermixed with script-supporting elements.[Exposed =Window ]
interface HTMLPictureElement : HTMLElement {
[HTMLConstructor ] constructor ();
};The picture element is a container
which provides multiple sources to its contained img element
to allow authors to declaratively control or give hints to the user agent about which image resource to use,
based on the screen pixel density, viewport size, image format, and other factors.
It represents its children.
The picture element is somewhat different from the similar-looking
video and audio elements. While all of them contain source
elements, the source element's src attribute
has no meaning when the element is nested within a picture element, and the resource
selection algorithm is different. Also, the picture element itself does not display
anything; it merely provides a context for its contained img element that enables it
to choose from multiple URLs.
source element HTML element specifies multiple media resources for the
Support in all current engines.
Support in all current engines.
picture element, before the img element.track elements.type — Type of embedded resource
media — Applicable media
src (in audio or video) — Address of the resource
srcset (in picture) — Images to use in different situations, e.g., high-resolution displays, small monitors, etc.
sizes (in picture) — Image sizes for different page layouts
width (in picture) — Horizontal dimension
height (in picture) — Vertical dimension
[Exposed =Window ]
interface HTMLSourceElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute USVString src ;
[CEReactions ] attribute DOMString type ;
[CEReactions ] attribute USVString srcset ;
[CEReactions ] attribute DOMString sizes ;
[CEReactions ] attribute DOMString media ;
[CEReactions ] attribute unsigned long width ;
[CEReactions ] attribute unsigned long height ;
};The source element allows authors to specify multiple alternative
source sets for img elements or multiple alternative
media resources for media
elements. It does not represent anything on its own.
The type attribute
may be present. If present, the value must be a valid MIME type string.
The media
attribute may also be present. If present, the value must contain a valid media query
list. The user agent will skip to the next source element if the value does
not match the environment.
The media attribute is only evaluated
once during the resource selection algorithm
for media elements. In contrast, when using the
picture element, the user agent will react to
changes in the environment.
The remainder of the requirements depend on whether the parent is a picture
element or a media element:
source element's parent is a picture elementThe srcset
attribute must be present, and is a srcset attribute.
The srcset attribute contributes the image sources to the source set, if the
source element is selected.
If the srcset attribute has any image candidate strings using a width descriptor, the
sizes attribute may also be present. If, additionally,
the following sibling img element does not allow
auto-sizes, the sizes attribute must be present.
The sizes
attribute is a sizes attribute, which contributes the source size to
the source set, if the source element is selected.
If the img element allows auto-sizes, then the sizes attribute can be omitted on previous sibling
source elements. In such cases, it is equivalent to specifying auto.
The source element supports dimension attributes. The
img element can use the width and height attributes of a source element, instead of
those on the img element itself, to determine its rendered dimensions and
aspect-ratio, as defined in the Rendering section.
The type attribute gives the type of the images in the
source set, to allow the user agent to skip to the next source element
if it does not support the given type.
If the type attribute is not
specified, the user agent will not select a different source element if it finds
that it does not support the image format after fetching it.
When a source element has a following sibling source element or
img element with a srcset attribute
specified, it must have at least one of the following:
A media attribute specified with a value that,
after stripping leading and trailing
ASCII whitespace, is not the empty string and is not an ASCII
case-insensitive match for the string "all".
A type attribute specified.
The src attribute must not be present.
source element's parent is a media elementThe src attribute
gives the URL of the media resource. The value must be a valid
non-empty URL potentially surrounded by spaces. This attribute must be present.
The type attribute gives the type of the media
resource, to help the user agent determine if it can play this media
resource before fetching it. The codecs parameter, which certain
MIME types define, might be necessary to specify exactly how the resource is encoded.
[RFC6381]
Dynamically modifying a source element's src or type attribute
when the element is already inserted in a video or audio element will
have no effect. To change what is playing, just use the src
attribute on the media element directly, possibly making use of the canPlayType() method to pick from amongst available
resources. Generally, manipulating source elements manually after the document has
been parsed is an unnecessarily complicated approach.
The following list shows some examples of how to use the codecs= MIME
parameter in the type attribute.
< source src = 'video.mp4' type = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"' > < source src = 'video.mp4' type = 'video/mp4; codecs="avc1.58A01E, mp4a.40.2"' > < source src = 'video.mp4' type = 'video/mp4; codecs="avc1.4D401E, mp4a.40.2"' > < source src = 'video.mp4' type = 'video/mp4; codecs="avc1.64001E, mp4a.40.2"' > < source src = 'video.mp4' type = 'video/mp4; codecs="mp4v.20.8, mp4a.40.2"' > < source src = 'video.mp4' type = 'video/mp4; codecs="mp4v.20.240, mp4a.40.2"' > < source src = 'video.3gp' type = 'video/3gpp; codecs="mp4v.20.8, samr"' > < source src = 'video.ogv' type = 'video/ogg; codecs="theora, vorbis"' > < source src = 'video.ogv' type = 'video/ogg; codecs="theora, speex"' > < source src = 'audio.ogg' type = 'audio/ogg; codecs=vorbis' > < source src = 'audio.spx' type = 'audio/ogg; codecs=speex' > < source src = 'audio.oga' type = 'audio/ogg; codecs=flac' > < source src = 'video.ogv' type = 'video/ogg; codecs="dirac, vorbis"' > The source HTML element insertion
steps, given insertedNode, are:
If insertedNode's parent is a media element that has no src attribute and whose networkState has the value NETWORK_EMPTY, then invoke that media
element's resource selection
algorithm.
If insertedNode's next sibling is an img element and its parent is
a picture element, then, count this as a relevant
mutation for the img element.
The source HTML element removing
steps, given removedNode and oldParent, are:
If removedNode's next sibling was an img element and
oldParent is a picture element, then, count this as a relevant mutation for the img element.
The IDL attributes src, type, srcset, sizes and media must reflect the respective
content attributes of the same name.
If the author isn't sure if user agents will all be able to render the media resources
provided, the author can listen to the error event on the last
source element and trigger fallback behavior:
< script >
function fallback( video) {
// replace <video> with its contents
while ( video. hasChildNodes()) {
if ( video. firstChild instanceof HTMLSourceElement)
video. removeChild( video. firstChild);
else
video. parentNode. insertBefore( video. firstChild, video);
}
video. parentNode. removeChild( video);
}
</ script >
< video controls autoplay >
< source src = 'video.mp4' type = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"' >
< source src = 'video.ogv' type = 'video/ogg; codecs="theora, vorbis"'
onerror = "fallback(parentNode)" >
...
</ video > img elementHTML element embeds an image into the document.">Element/img
Support in all current engines.
element, providing the properties and methods used to manipulate image elements.">HTMLImageElement
Support in all current engines.
usemap attribute: Interactive content.picture element, after all source elements.alt — Replacement text for use when images are not available
src — Address of the resource
srcset — Images to use in different situations, e.g., high-resolution displays, small monitors, etc.
sizes — Image sizes for different page layouts
crossorigin — How the element handles crossorigin requests
usemap — Name of image map to use
ismap — Whether the image is a server-side image map
width — Horizontal dimension
height — Vertical dimension
referrerpolicy — Referrer policy for fetches initiated by the element
decoding — Decoding hint to use when processing this image for presentation
loading — Used when determining loading deferral
fetchpriority — Sets the priority for fetches initiated by the element
alt attribute: for authors; for implementers.[Exposed =Window ,
LegacyFactoryFunction =Image (optional unsigned long width , optional unsigned long height )]
interface HTMLImageElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString alt ;
[CEReactions ] attribute USVString src ;
[CEReactions ] attribute USVString srcset ;
[CEReactions ] attribute DOMString sizes ;
[CEReactions ] attribute DOMString ? crossOrigin ;
[CEReactions ] attribute DOMString useMap ;
[CEReactions ] attribute boolean isMap ;
[CEReactions ] attribute unsigned long width ;
[CEReactions ] attribute unsigned long height ;
readonly attribute unsigned long naturalWidth ;
readonly attribute unsigned long naturalHeight ;
readonly attribute boolean complete ;
readonly attribute USVString currentSrc ;
[CEReactions ] attribute DOMString referrerPolicy ;
[CEReactions ] attribute DOMString decoding ;
[CEReactions ] attribute DOMString loading ;
[CEReactions ] attribute DOMString fetchPriority ;
Promise <undefined > decode ();
// also has obsolete members
};An img element represents an image.
An img element has a dimension
attribute source, initially set to the element itself.
element.">HTMLImageElement/src
Support in all current engines.
HTML element embeds an image into the document.">Element/img#attr-srcset
Support in all current engines.
The image given by the src
and srcset attributes, and
any previous sibling source elements' srcset
attributes if the parent is a picture element, is the embedded content; the value of
the alt attribute provides
equivalent content for those who cannot process images or who have image loading disabled (i.e. it
is the img element's fallback content).
The requirements on the alt attribute's value are described
in a separate section.
The src attribute must be present, and must contain a
valid non-empty URL potentially surrounded by spaces referencing a non-interactive,
optionally animated, image resource that is neither paged nor scripted.
The requirements above imply that images can be static bitmaps (e.g. PNGs, GIFs, JPEGs), single-page vector documents (single-page PDFs, XML files with an SVG document element), animated bitmaps (APNGs, animated GIFs), animated vector graphics (XML files with an SVG document element that use declarative SMIL animation), and so forth. However, these definitions preclude SVG files with script, multipage PDF files, interactive MNG files, HTML documents, plain text documents, and the like. [PNG] [GIF] [JPEG] [PDF] [XML] [APNG] [SVG] [MNG]
The srcset attribute may also be present, and is a
srcset attribute.
The srcset attribute and the src attribute (if width
descriptors are not used) contribute the image sources
to the source set (if no source element was selected).
If the srcset attribute is present and has any image candidate strings using a width
descriptor, the sizes attribute must also be present.
If the srcset attribute is not specified, and the
loading attribute is in the Lazy state, the sizes attribute may be specified with the value "auto" (ASCII case-insensitive). The sizes attribute is a sizes attribute,
which contributes the source size to the source set (if no
source element was selected).
An img element allows auto-sizes if:
loading attribute is in the Lazy state, andsizes attribute's value is "auto" (ASCII case-insensitive), or starts with "auto," (ASCII case-insensitive).