The <picture> element Participate: Send feedback to whatwg@whatwg.org This version: 2013-11-24 Previous version: 2013-11-24 To the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 7 November 2013, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0, which is available at http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0.

Abstract The picture element gives authors a way to control which image resource the user agent presents to a user based on a media query and/or support for a particular image format. The primary purpose of the picture element is to address use cases that are left unaddressed by the srcset attribute; the most important being art direction . Other use cases, such as matching media features and media types and matching on supported image formats , are also addressed by this specification.

Content model: Transparent, allowing zero or more <source> elements, but with no interactive content descendants and no <picture> descendants. Content attributes: Global attributes width — Horizontal dimension height — Vertical dimension DOM interface: interface HTMLPictureElement : HTMLElement { attribute DOMString src; attribute DOMString srcset; attribute unsigned long width; attribute unsigned long height; readonly attribute boolean complete; };

In interactive visual media, if support for images has been enabled, the picture element represents an image.

In non-visual media, and in visual media if images have been disabled, the picture element represents its fallback content instead.

This allows implementations to render broken <picture> in the same way as broken <img> without complexity of dynamically exposing full fallback content.

Controlling image

This specification defines behavior of the <picture> element in terms of controlling an <img> element displayed in its place. When the specification refers to controlling image element, user agents should perform steps as defined for the <img> element. The controlling image element should not be exposed in DOM.

Events that are fired on the controlling image must be fired on the picture element.

This is intended to allow user agents to implement <picture> via <img> in shadow DOM or reuse of most of <img> element's implementation.

Attributes

The src , srcset , width , height and complete IDL attributes must return value of the corresponding IDL attribute of the controlling image.

On setting the width and height attributes must act as if they reflected the respective content attributes of the <picture> element and immediately run the source selection algorithm starting from step 3.

When the src or srcset IDL attribute is set:

If the src / srcset IDL attribute (respectively) of the controlling image is equal to the value being set, then abort these steps. Remove all <source> children of the picture element. Insert new <source> element as child of the picture element with src / srcset attribute (respectively) equal to the value being set and let it be the selected source. Immediately run the source selection algorithm starting from step 3.

These attributes are supposed to behave as similarly to Image as possible, specifically setting of src should guarantee that source being used. "Run the source selection algorithm starting from step 3" ensures that reading of src / srcset / width / height immediately after setting returns value that was set (rather than old value until source selection is re-run later).

Fallback content

User agents may expose fallback content to accessibility tools in one of two ways:

by exposing fallback content as-is, as if the picture element did not replace the fallback content. <source> elements MUST NOT be announced.

elements MUST NOT be announced. by presenting fallback content as plain text, as if it was set as alt attribute in the controlling image. The plain text fallback should be extracted from fallback content using algorithm similar to innerText , with additional requirements: content of alt attributes of <img> elements in the fallback content MUST be included, content of <script> and <style> descendants must be ignored, elements that don't represent Phrasing content must imply breaks in the text (e.g. imply whitespace before and after the element).

attribute in the controlling image. The plain text fallback should be extracted from fallback content using algorithm similar to , with additional requirements:

Fallback-as-plaintext is intended to allow integration with existing accessibility tools that may support only primitive fallback for images due to limitations of <img alt> . Once implementations of <picture> and accessibility tools mature this simplification may be removed.

In interactive visual media with image support enabled user agents SHOULD NOT focus elements inside fallback content.

Source selection algorithm

"Schedule run of source selection algorithm" means the algorithm described below should be executed no earlier than on the next run of the event loop. User agent may choose to delay and coalesce runs of this algorithm.

To prevent race conditions JavaScript MUST NOT be allowed to mutate DOM while this algorithm is being executed, and JavaScript SHOULD NOT be allowed to observe source change synchronously (except when src / srcset is set by JavaScript explicitly).

This may be achieved simply by running the algorithm on the main JS thread or before any JS is allowed to run.

For each <source> child node (in the HTML namespace) of the picture element, in tree order: If the current source node doesn't have either non-empty src or srcset attribute, ignore this source and continue evaluating sources. If the current source node has a non-empty type attribute and the type is not supported by the user agent, ignore that source and continue evaluating sources. If the current source node has non-empty media attribute: If the Media Query contained in the attribute cannot be evaluated temporarily (e.g. depends on layout that hasn't been done yet) then schedule source selection algorhtm to be re-run when the Media Query can be evaluated and abort these steps.

If the Media Query does not match, then ignore this source and continue evaluating sources. Use the current source node as the selected source If no source was selected then continue these steps as if <source> element with no attributes was the selected source. Copy src , srcset , width , and height content attributes (if present) from the selected source to the controlling image, or delete them accordingly if they're not present on selected source. Copy width and height content attributes (if present) from the picture element to the controlling image.

Live updates

User agent MUST schedule run of the source selection algorithm when:

children of the picture element are mutated (e.g. insertion/deletion of <source> elements or change of their attributes),

elements or change of their attributes), media queries in media attributes of <source> children start or cease to match.

User agents may optimize this and avoid actually running source selection algorithm if the change could not possibly affect which source is selected (e.g. new <source> was added later in the document than the currently selected source).

Preloading

<img> elements in fallback content of the <picture> element should be treated as inert and SHOULD NOT initiate image downloads.