Picturefill A responsive image polyfill

The picture element and associated features are W3C standard HTML features that 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 is a JavaScript file (or a polyfill to be more specific) that 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 is developed and maintained by , with help from the members of the Responsive Images Community Group and the developer community at large. For Picturefill version 2, a special thanks goes to Shawn Jansepar for all his work on polyfilling the new spec.

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 the code project site on Github : Picturefill on Github.

Downloading Picturefill

Picturefill Version 2.1.0

For native picture element support, you'll want Picturefill version 2. These downloads include the matchMedia polyfill for browsers that need it (like IE9).

Version 1.2.1 (latest stable version)

Version 1.2.1 of Picturefill is available if you are interested in the older markup pattern that uses span elements. This version is a lot lighter in weight than version 2 and allows for a fallback image in browsers that have JavaScript disabled (whereas Picturefill version 2 only offers alt text as a fallback for non-JS browsers without picture support).

Getting Started with Picturefill Version 2

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.

Here's our recommended snippet:

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

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).

Basic 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. You may find that the new img features may be all you need. Let's cover those first.

Using img with srcset & sizes attributes

The sizes syntax is used to define the size of the image across a number of breakpoints. srcset then defines an array of images and their inherent sizes. 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!

An img with "srcset" and sizes" attributes:

<img sizes="(min-width: 40em) 80vw, 100vw"
srcset="examples/images/medium.jpg 375w, examples/images/medium.jpg 480w, examples/images/large.jpg 768w" alt="A giant stone face at The Bayon temple in Angkor Thom, Cambodia">

Here's how that renders in the browser. Feel free to resize to see it change.

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

View standalone demo

Using the picture element

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 sources with other layout conditions in your designs.

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/large.jpg" media="(min-width: 800px)">
	<img srcset="examples/images/medium.jpg" alt="A giant stone face at The Bayon temple in Angkor Thom, Cambodia">
</picture>

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="A giant stone face at The Bayon temple in Angkor Thom, Cambodia">
</picture>

Here's how that renders in the browser. Feel free to resize to see it change.

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

View standalone demo

More Picture markup examples

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>
	<!--[if IE 9]><video style="display: none;"><![endif]-->
	<source srcset="examples/images/large.jpg, examples/images/extralarge.jpg 2x" media="(min-width: 800px)">
	<source srcset="examples/images/small.jpg, examples/images/medium.jpg 2x">
	<!--[if IE 9]></video><![endif]-->
	<img srcset="examples/images/small.jpg, examples/images/medium.jpg 2x" alt="A giant stone face at The Bayon temple in Angkor Thom, Cambodia">
</picture>
A giant stone face at The Bayon temple in Angkor Thom, Cambodia

View standalone demo

media example with one webp source qualified with a type attribute.

Note: Picturefill supports SVG and WebP types on any source element, and will disregard a source if its type is not supported in a particular environment:

<picture>
	<!--[if IE 9]><video style="display: none;"><![endif]-->
	<source srcset="examples/images/large.webp" media="(min-width: 800px)" type="image/webp">
	<source srcset="examples/images/large.jpg" media="(min-width: 800px)">
	<source srcset="examples/images/medium.jpg" media="(min-width: 400px)">
	<!--[if IE 9]></video><![endif]-->
	<img srcset="examples/images/small.jpg" alt="A giant stone face at The Bayon temple in Angkor Thom, Cambodia">
</picture>
A giant stone face at The Bayon temple in Angkor Thom, Cambodia

View standalone 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:

Browser Support

Picturefill supports a broad range of browsers and devices, provided that you stick with the standard 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: