The picture element

Abstract

The picture element provides a way to group multiple versions of an image based on different characteristics (e.g., format, resolution, cropping, etc.). This allows the user agent to select the optimum image to present to an end-user based on the browser's environmental conditions and constraints.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This specification was published by the Responsive Images Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

Table of Contents

1. 1 Introduction
   1. 1.1 Example of usage
   2. 1.2 Relationship to srcset
2. 2 Conformance
3. 3 Definitions
4. 4 The picture element
5. 5 Algorithm for deriving the source image
6. Open Issues
7. Acknowledgements
8. Normative references

1 Introduction

This section is non-normative.

This specification provides developers with a means to declare multiple sources for an image, and, through [CSS3-MEDIAQUERIES] (CSS Media Queries), it gives developers control as to when those images are to be presented to a user. This is achieved by introducing a new picture element to [HTML] that makes use of the source element. The picture element remains backwards compatible with legacy user agents by degrading gracefully through fallback content (i.e., through the img element) while also potentially providing better accessibility than the existing img element.

By relying on [CSS3-MEDIAQUERIES], a user agent can respond to changes in the browsing environment by selecting the image source that most closely matches the browsing environment - thus embodying a technique known as responsive web design directly in the HTML markup. Media features that a user agent can potentially respond to include, but are not limited to, pixel widths and heights, and pixel densities, as well as environmental lighting conditions, changes in orientation, and changes in media type such as going from screen to print.

This specification also defines the HTMLPictureElement programming interface, which affords developers a set of attributes and methods for interacting with picture elements through ECMAScript.

1.1 Example of usage

This section is non-normative.

This first sample shows how to combine the picture element with the source element, while also providing fallback content for legacy user agents through the img element.

<picture width="500" height="500">
   <source media="(min-width: 45em)" src="large.jpg">
   <source media="(min-width: 18em)" src="med.jpg">
   <source src="small.jpg">
   <img src="small.jpg" alt="">
   <p>Accessible text</p>
</picture>

This second example shows how the picture element can be used with the srcset attribute to provide a range of sources suitable for a given media query:

<picture width="500" height="500">
   <source media="(min-width: 45em)" srcset="large-1.jpg 1x, large-2.jpg 2x">
   <source media="(min-width: 18em)" srcset="med-1.jpg 1x, med-2.jpg 2x">
   <source srcset="small-1.jpg 1x, small-2.jpg 2x">
   <img src="small-1.jpg" alt="">
   <p>Accessible text</p>
</picture>

1.2 Relationship to srcset

The `srcset` attribute allows authors to define various image resources and “hints” that assist a user agent in determining the most appropriate image source to display. Given a set of image resources, the user agent has the option of either following or overriding the author’s declarations to optimize the user experience based on criteria such as display density, connection type, user preferences, and so on.

The `picture` element defines conditions under which the UA should follow the author's explicit instructions when selecting which resource to display. This includes image sources with inherent sizes designed to align with layout variations specified in CSS media queries ( see: design breakpoints, media features and types and relative units ) or content variations for increased clarity and focus based on the client’s display size.

The proposed solutions are not mutually exclusive, and may work together to address the complete set of use cases and requirements for responsive images.

2 Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

This specification has the same conformance requirements and applies to the same conformance classes as [HTML].

Implementations that use ECMAScript to expose the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the [WEBIDL] specification.

3 Definitions

The following terms are used throughout this specification so they are gathered here for the readers convenience. The following list of terms is not exhaustive; other terms are defined throughout this specification.

The follow terms are defined by the [HTML] specification: img element, source element, fallback content, and valid media query.

4 The picture element

Categories:

Flow content.

Phrasing content.

Embedded content.

Palpable content.

Contexts in which this element can be used:

Where embedded content is expected.

Content model:

If zero descendents, then transparent.

One or more source elements.

Zero or one img element, serving as fallback content.

Content attributes:

Global attributes

alt

src

srcset

crossorigin

usemap

ismap

width

height

DOM interface:

[NamedConstructor=Picture,
 NamedConstructor=Picture(unsigned long width),
 NamedConstructor=Picture(unsigned long width, unsigned long height)]
HTMLPictureElement : HTMLImageElement{
   attribute DOMString alt;
   attribute DOMString src;
   attribute DOMString crossOrigin;
   attribute DOMString srcset;
   readonly attribute DOMString currentSrc;
   attribute DOMString useMap;
   attribute boolean isMap;
   readonly attribute DOMString media;
   void load();
}

The picture element used for displaying an image that can come from a range of sources (including the src and srcset attributes). Which image the user agent displays depends on the algorithm for deriving the source image. The value of the alt attribute provides equivalent content for those who cannot process images or who have image loading disabled.

The requirements on the alt attribute's value are described in the img section.

The src attribute may be present, and if present 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 root element), animated bitmaps (APNGs, animated GIFs), animated vector graphics (XML files with an SVG root 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 so forth. [PNG] [GIF] [JPEG] [PDF] [XML] [APNG] [SVG] [MNG]

The srcset attribute may be present, and if present must conform to the srcset specification.

picture . currentSrc

Returns the address of the current image resource.

Returns the empty string when there is no image resource.

There are three ways to specify an image resource, the src attribute, the srcset attribute, or source elements. The srcset attribute overrides both the src attribute and the elements; the src attribute overrides the elements.

The crossorigin attribute is a CORS settings attribute. Its purpose is to allow images from third-party sites that allow cross-origin access to be used with canvas.

On getting the media IDL attribute, the user agent must return the media query that matches the current environment.

It is recommended that for cases where a single image source is available, and where no responsive adoption is needed, authors use the img element. Authors can use the srcset attribute for simple resized image sources.

The chosen image is the embedded content.

For user agents that don't support the picture element, an author can provide an img element as fallback content. User agents that support the picture element should not show this content to the user: it is intended for legacy user agents that do not support picture, so that a legacy img element can be shown instead.

Authoring requirement: as with the img element, documents must not use the picture element as a layout tool. In particular, picture elements should not be used to display transparent images, as they rarely convey meaning and rarely add anything useful to the document.

When used with the picture element, a document should only contain source elements need to represent the same subject matter, but cropping and zooming can differ.

The usemap attribute, if present, can indicate that the image has an associated image map.

The ismap attribute, when used on an element that is a descendant of an a element with an href attribute, indicates by its presence that the element provides access to a server-side image map. This affects how events are handled on the corresponding a element.

The ismap attribute is a boolean attribute. The attribute must not be specified on an element that does not have an ancestor a element with an href attribute.

5 Algorithm for deriving the source image

The algorithm for deriving the source image as follows. The result is the image source to be used by the picture element, which reflects the picture element's src IDL attribute:

<picture id="pictureElement">
   <source media="(min-width: 45em)" srcset="large-1.jpg 1x, large-2.jpg 2x">
   <source media="(min-width: 18em)" srcset="med-1.jpg 1x, med-2.jpg 2x">

   <!-- assume media all -->
   <source srcset="small-1.jpg 1x, small-2.jpg 2x">

   <!-- the following are ignored -->
   <source media=" is the message " srcset="">
      
</picture>

//assume #pictureElement is magically scoped to the corresponding element.
@media all{
   #pictureElement{
      background-image: image-set(small-1.jpg 1x, small-2.jpg 2x);
   }
}

@media all and (min-width: 45em){
   #pictureElement{
      background-image: image-set(large-1.jpg 1x, large-2.jpg 2x);
   }
}

@media all and (min-width: 18em){
   #pictureElement{
      background-image: image-set(med-1.jpg 1x, med-2.jpg 2x);
   }
}

A user agent may override requests for higher-resolution images based on user preferences. For example: “always request high-resolution images,” “always request low-resolution images,” and “request high-resolution images as bandwidth permits” based on the bandwidth information available to the browser.

The alt attribute does not represent advisory information. User agents must not present the contents of the alt attribute in the same way as content of the title attribute.

While user agents are encouraged to repair cases of missing alt attributes, authors must not rely on such behavior. Requirements for providing text to act as an alternative for images are described in detail in the img section.

Open Issues

We are tracking open issues on Github. Please help close them!

Reference implementations

We have a list of current users, polyfills, prototypes, and implementations on Github.

Acknowledgements

A complete list of participants of the Responsive Images Community Group is available at the W3C Community Group Website.

Normative references

[CSS3-MEDIAQUERIES]

Media Queries. (status).

[HTML]

HTML5. (status).

[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels.

[WEBIDL]

Web IDL. (status).