Picturefill

A responsive image polyfill

Officially endorsed by the RICG

The picture element, srcset and sizes attributes, and associated features allow web developers to deliver an appropriate image to every user depending on a variety of conditions like screen size, viewport size, screen resolution, and more. Picturefill enables support for the picture element and associated features in browsers that do not yet support them, so you can start using them today!

Picturefill development is sponsored by and , and maintained by the Picturefill Team.

Contributing, Bug Reports, and More information

For more information on the development of Picturefill and how you can file bugs or contribute fixes, check out the project on GitHub.

Downloading Picturefill

Picturefill Version 3.0.0 (Alpha)

Version 3 is a full rewrite of the codebase featuring optimized performance, better emulation of native behavior, and new spec-based parsers. It also handles some of the quirks, shortcomings, and edge cases related to first-generation native implementations. For IE 9 and earlier, version 3 includes a small shim that polyfills the use of common media conditions (min-width, max-width, min-height, max-height). If you need old IE support for other media conditions, such as orientation or aspect-ratio, please additionally include the matchMedia polyfill. Feedback on this alpha release is welcome. If you encounter problems, please file a issue on Github.

Picturefill Version 2.3.1 (Stable)

This is the old way, and it's still available. Please note however that because of a recently-fixed bug, you should absolutely not be using any version of Picturefill prior to 2.3.1. If you are, please update immediately. These downloads include the matchMedia polyfill for browsers that need it (like IE9).

Getting Started with Picturefill

For basic usage of Picturefill: download one of the files listed above and reference it from the head section of your HTML document with the following code:

<script src="picturefill.js"></script>

To allow your page to load more efficiently, we'd recommend adding an async attribute to that script tag as well. This tells the browser that it can load picturefill asynchronously, without waiting for it to finish before loading the rest of the document. If you add this attribute, you'll need to add a line of script before the script tag as well to allow older browsers to recognize picture elements if it encounters them in the page before picturefill has finished loading.

Reccomended Usage:

<head>
  <script>
    // Picture element HTML5 shiv
    document.createElement( "picture" );
  </script>
  <script src="picturefill.js" async></script>
</head>

Note that if you are already including a recent version of the HTML5 Shiv (sometimes packaged with Modernizr), you may not need this line as it is included there as well. Also, more advanced users may not need this may choose to load Picturefill dynamically using a script loader like Require.js, (AMD and CommonJS support is included in the script).

Markup Patterns

Once you've included picturefill.js, you can start adding responsive image elements to your site. Picturefill adds support for both the picture element and also new responsive attributes to the img element.

There are a number of different use cases addressed by some combination of features from the responsive images specification—here are some of the most common ones:

Using the `srcset` attribute

The srcset attribute (without sizes) is used to serve larger—but otherwise identical—image sources to high resolution displays only.

<img srcset="examples/images/large.jpg 1x, examples/images/extralarge.jpg 2x" alt="…">

Note that the 2x source will be shown at the inherent width of the 1x source. The two sources will occupy the same space in your layout, but the 2x source will be at double the pixel density. This only applies to the natural size of the img—any sizing changes done in CSS are unchanged.

Here's how that renders on your display:

A giant stone face at The Bayon temple in Angkor Thom, Cambodia

Using the `srcset` & `sizes` attributes

The srcset and sizes syntaxes are used to provide the browser with a list of image sources that are identical apart from their size (same aspect ratio, same focal point) and how they’ll be displayed, then allow the browser to choose the source best for the user’s current viewport size, display density, and the size of that image in the page layout.

The sizes syntax is used to define the spaces your image will occupy in your layout. srcset then defines a list of images and their inherent widths. This allows the browser to choose the smallest appropriate source for the size available in that part of the layout, rather than the viewport size alone.

It's beyond the scope of this guide to get into much detail about how to use the new srcset & sizes attributes, so we'd recommend reading the following post by Eric Portis: Srcset and Sizes. Read that first, then check out the demos below!

<img 
  sizes="(min-width: 40em) 80vw, 100vw"
  srcset="examples/images/medium.jpg 375w, 
          examples/images/large.jpg 480w,
          examples/images/extralarge.jpg 768w" 
  alt="…">

Here's how that renders on your display at your current viewport size:

A giant stone face at The Bayon temple in Angkor Thom, Cambodia Standalone srcset and sizes demo

Using the `picture` element

The picture element is used when you need explicit control over which source is shown at set viewport sizes.

The picture element requires a little more markup than the example above, but it allows you to use features like CSS3 Media Queries to pair image source with varying sizes, zoom levels, and aspect ratios with the layout conditions in your designs. It should not, however, be used to serve radically different image sources—all sources must be described by the alt attribute of the inner img.

Your picture element should contain a series of source elements followed by an img element. Each source element must have a srcset attribute specifying one or more image url sources (which can use expanded srcset syntax if desired for resolution switching), and the img element should have a srcset attribute for fallback purposes as well (some browsers like Android 2.3's won't see the source elements). Additionally, you may add a media attribute containing CSS3 Media Queries, and/or a sizes attribute to pair with srcset.

Here's one with srcset and media. The first source with a media attribute that matches the user’s context will determine the src of the img element at the end, so you’ll want to present larger options first when using min-width media queries (like in the examples below), and larger options last when using max-width media queries.

<picture>
  <source srcset="examples/images/extralarge.jpg" media="(min-width: 1000px)">
  <source srcset="examples/images/art-large.jpg" media="(min-width: 800px)">
  <img srcset="examples/images/art-medium.jpg" alt="…">
</picture>

Here's how that renders at your current viewport size:

A giant stone face at The Bayon temple in Angkor Thom, Cambodia Standalone picture demo

Supporting Picture in Internet Explorer 9

While most versions of IE (even older ones!) are supported well, IE9 has a little conflict to work around. To support IE9, you will need to wrap a video element wrapper around the source elements in your picture tag. You can do this using conditional comments, like so:

<picture>
  <!--[if IE 9]><video style="display: none;"><![endif]-->
  <source srcset="examples/images/extralarge.jpg" media="(min-width: 1000px)">
  <source srcset="examples/images/large.jpg" media="(min-width: 800px)">
  <!--[if IE 9]></video><![endif]-->
  <img srcset="examples/images/medium.jpg" alt="…">
</picture>

`media` and `srcset` syntax:

The 1x, 2x syntax in srcset acts as a shorthand for more complex resolution media queries. When natively supported, srcset will allow the UA to override requests for higher-resolution options based on a bandwidth limitations or a user preference (see #9 in the Responsive Images Use Cases and Requirements).

<picture>
  <source srcset="examples/images/large.jpg, examples/images/extralarge.jpg 2x" media="(min-width: 800px)">
  <img srcset="examples/images/small.jpg, examples/images/medium.jpg 2x" alt="…">
</picture>
A giant stone face at The Bayon temple in Angkor Thom, Cambodia Standalone extended picture demo

The `type` attribute in `picture`

The types attribute is used to send an alternate image source format only to browsers that support that format, and a fallback source to browsers that do not.

Picturefill supports SVG and WebP as part of its core, but the following MIME types can be used via the “typesupport” plugin:

<picture>
  <source srcset="examples/images/large.webp" type="image/webp">
  <img srcset="examples/images/large.jpg" alt="…">
</picture>

Here's how that renders in your browser:

A giant stone face at The Bayon temple in Angkor Thom, Cambodia Standalone type attribute demo

Picturefill JavaScript API

Under ordinary circumstances, you likely won't need to do more than include picturefill.js in your page, but in some situations you may want to run picturefill's function manually yourself, and there are a few options to keep in mind:

The Picturefill function

Picturefill.js exposes a single global function: the picturefill() function. picturefill() is automatically called one or more times while a page is loading, and it also is triggered when the browser window is resized (or on orientation change). You can run the picturefill() function at any time in JavaScript yourself as well, which may be useful after making updates to the DOM, or when conditions relevant to your application change:

picturefill();

Picturefill function options

When running the picturefill() function, you can pass options specifying the following settings:

Picturefill source selection option

By default Picturefill tries to mimic the resource selection algorithm of Chrome (except that Picturefill, unlike the browser, doesn't know which image files are already cached). Picturefill 3.0 also comes with a new image custom source selection algorithm unique to Picturefill called saveData. The saveData algorithm weights the resource selection algorithm towards smaller image candidates on very high dppx devices (3dppx +), to conserve bandwidth.

To use saveData, create a picturefillCFG array that runs before the main plugin: 

//generating the config array
window.picturefillCFG = window.picturefillCFG || [];
picturefillCFG.push([ "algorithm", "saveData" ]);

Developer feedback on this new algorithm is welcome, especially if you've got some hard data.

Browser Support

Picturefill supports a broad range of browsers and devices, provided that you stick with the markup conventions documented above.

Support caveats to keep in mind

Picturefill is tested broadly and works in a large number of browsers. That said, it does have some browser support considerations to keep in mind: