Responsive Images Community Group W3C

The picture element

An HTML extension for adaptive images

W3C Working Draft 26 February 2013

This Version:
Latest version:
Previous version:
Latest Editor's draft:
Join the Responsive Images Community Group
Public mailing list
IRC: #respimg on W3C's IRC server
Version history:
Github commits (RSS)
Github commits on Twitter
Participants of the Responsive Images Community Group
Marcos Cáceres, Data.Driven
Mat Marquis
Yoav Weiss
Adrian Bateman, Microsoft Corporation
RICG Final Specification Licensing Commitments:


The picture element is an image container whose source content is determined by one or more CSS media queries.

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

This is a work in progress! For the latest updates from the HTML WG and RICG, possibly including important bug fixes, please look at the editor's draft instead. If you find any bugs, typos, or issues please file a bug!

This is a First Public Working Draft.

This document was published by the HTML Working Group as a Working Draft, but was developed in collaboration with the Responsive Images Community Group (see licensing commitments). If you are not a HTML working group member and wish to make comments regarding this document please send them to (subscribe, archives). If you are a HTML working group member and wish to make comments regarding this document, please send them to (subscribe, archives). All feedback is welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

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.

Example 1
<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>
Issue 1

The following example assumes we can get the srcset attribute supported on HTML's source element. See issue 64.

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:

Example 2
<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>

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

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
DOM interface:
 NamedConstructor=Picture(unsigned long width),
 NamedConstructor=Picture(unsigned long width, unsigned long height)]
HTMLPictureElement : HTMLImageElement{
   readonly attribute DOMString media; 

The picture element used for displaying an image that can come from a range of sources (see srcset attribute). Which image the user agent displays depends on the algorithm for deriving the source image.

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.

Issue 2

It should be codified that this is not a mechanism by which to swap disparate images depending on screen size. See bug 18384.

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:


What we want to do is have the picture behave exactly the same as an img element, but with the only difference being that it is source elements is used to determine the value of the src IDL attribute (and hence what image content is displayed). How that is determined is through using the media attribute attribute of the source element.

So, to derive the source image: ignoring any sources whose type is not supported by the browser, gather all the media queries from the source elements' media attributes into a "stylesheet", in document order. Any missing media attributes are just assumed to mean "all". Any media attributes that are not valid media queries are ignored. So, given the following:

<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="">

Becomes the rough CSS equivalent of (a virtual stylesheet for the document?):

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

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

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

The API then just works the same as per images. Events are fired in the same way as if the image's src IDL attribute had been set manually by the author.

The resource fetching behavior of then governed by CSS Image Values and Replaced Content Module Level 4.

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.

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.


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

Participants of the Responsive Images Community Group at the time of publication were: George Adamson, Marie Alhomme, John Allan, Joshua Allen, Angely Alvarez, Aaryn Anderson, Philip Andrews, Phil Archer, Justin Avery, Michael Balensiefer, Toni Barrett, Bruno Barros, Paul Barton, Adrian Bateman, Jesse Renée Beach, Robin Berjon, Seth Bertalotto, Nicolaas Bijvoet, Andreas Bovens, J. Albert Bowden, Adam Bradley, Rodrigo Brancher, Gordon Brander, Paul Bridgestock, Aaron Brosey, Cory Brown, mairead buchan, Kris Bulman, Ariel Burone, Mathias Bynens, Marcos Caceres, Rusty Calder, Ben Callahan, Loïc Calvy, Chuck Carpenter, Brandon Carroll, Frederico Cerdeira, David Clements, Geri Coady, Anne-Gaelle Colom, Cyril Concolato, Pete Correia, Andy Crum, Jason Daihl, Francois Daoust, Kevin Davies, Robert Dawson, Ryan DeBeasi, Anna Debenham, Darryl deHaan, David Demaree, George DeMet, Ian Devlin, peter droogmans, Marlene Frykman, Dennis Gaebel, Nicolas Gallagher, Miguel Garcia, Rafael Garcia Lepper, Larry Garfield, Peter Gasston, David Goss, Chris Grant, Petra Gregorova, Jason Grigsby, Antoine Guergnon, Jeff Guntle, Aaron Gustafson, Jason Haag, Patrick Haney, Anselm Hannemann, chris hardy, Vincent Hardy, Dominique Hazaël-Massieux, Chris Hilditch, Nathan Hinshaw, Sean Hintz, John Holt Ripley, Shane Hudson, Tomomi Imura, Philip Ingrey, Brett Jankord, Scott Jehl, Dave Johnson, Nathanael Jones, Michael Jovel, Chao Ju, Tim Kadlec, Frédéric Kayser, Jin Kim, Andreas Klein, Peter Klein, John Kleinschmidt, Daniel Konopacki, Zoran Kurtin, Gerardo Lagger, Adam Lake, Chris Lamothe, Tom Lane, Matthieu Larcher, Bruce Lawson, Zach Leatherman, Silas Lepcha, Kornel Lesinski, Chris Lilley, grappler login, Tania Lopes, André Luís, Jacine Luisi, David Maciejewski, Kevin Mack, Ethan Malasky, Josh Marinacci, Eduardo Marques, Mathew Marquis, Daniel Martínez, Tom Maslen, Jacob Mather, Chris McAndrew, Denys Mishunov, Sabine Moebs, Ian Moffitt, Orestis Molopodis, jason morita, David Moulton, Brian Muenzenmeyer, Emi Myoudou, Irakli Nadareishvili, Christian Neuberger Jr, David Newton, Todd Nienkerk, Kothary Nishant, Ashley Nolan, Kenneth Nordahl, Lewis Nyman, Alejandro Oviedo, David Owens, Fernando Pasik, Andrew Pez Pengelly, Hassadee Pimsuwan, Manik Rathee, François REMY, Nestor Rojas, Adrian Roselli, Chris Ruppel, Oguzcan Sahin, Viljami Salminen, Luca Salvini, Luke Sands, aron santa, Jad Sarout, Brandon Satrom, Christoph Saxe, Doug Schepers, Jason Schmidt, Christopher Schmitt, Joe Schmitt, Boaz Sender, Tomoyuki Shimizu, Ariel Shkedi, Jen Simmons, Katerina Skotalova, Michael[tm] Smith, Ignacio Soriano Cano, Aaron Stanush, Jared Stilwell, Matt Stow, Kevin Suttle, Satoru Takagi, Philipp Tautz, James Tudsbury, Jacob van Zijp, Jitendra Vyas, Yoav Weiss, George White, Matt Wilcox, Richard Wild, John Albin Wilkins, Owen Winkler, Jeremy Worboys, Mike Wu, Carlos Zepeda, and jintian zheng.

Contributions also from: Ilya Grigorik and Leon de Rijke.

Normative references

Media Queries. (status).
HTML5. (status).
Key words for use in RFCs to Indicate Requirement Levels.
Web IDL. (status).