<p>The <ahref="http://picture.responsiveimages.org/">picture element</a> 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 <em>polyfill</em> to be more specific) that enables support for the <code>picture</code> element and associated features in browsers that do not yet support them, so you can start using them today!</p>

<p>Picturefill is developed and maintained by <ahref="http://filamentgroup.com"><imgsrc="http://filamentgroup.com/images/fg-logo-icon-lrg.png"class="filament-logo"alt="Filament Group"></a>, with help from the members of the <ahref="http://picture.responsiveimages.org/">Responsive Images Community Group</a> and the developer community at large. For Picturefill version 2, a special thanks goes to <ahref="https://github.com/jansepar">Shawn Jansepar</a> for all his work on polyfilling the new spec.</p>

<h3id="contributing">Contributing, Bug Reports, and More information</h3>

<p>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 : <ahref="https://github.com/scottjehl/picturefill">Picturefill on Github.</a></p>

<h2id="download">Downloading Picturefill</h2>

<h3>Picturefill Version 2.2.0</h3>

<p>For native <code>picture</code> element support, you'll want Picturefill version 2. These downloads include the <ahref="https://github.com/paulirish/matchMedia.js/">matchMedia polyfill</a> for browsers that need it (like IE9).</p>

<p>Version 1.2.1 of Picturefill is available if you are interested in the older markup pattern that uses <code>span</code> 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 <code>alt</code> text as a fallback for non-JS browsers without <code>picture</code> support).</p>

<ul>

<li><ahref="https://github.com/scottjehl/picturefill/blob/1.2.1/picturefill.js">Picturefill version 1.2.1</a></li>

<p>To allow your page to load more efficiently, we'd recommend adding an <code>async</code> attribute to that <code>script</code> 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 <code>script</code> tag as well to allow older browsers to recognize <code>picture</code> elements if it encounters them in the page before picturefill has finished loading. </p>

<p><strong>Here's our recommended snippet:</strong></p>

<pre><code>&lt;script&gt;

// Picture element HTML5 shiv

document.createElement( &quot;picture&quot; );

&lt;/script&gt;

&lt;script src=&quot;picturefill.js&quot; async&gt;&lt;/script&gt;

</code></pre>

<pclass="note">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).</p>

<h2id="examples">Basic markup patterns</h2>

<p>Once you've included picturefill.js, you can start adding responsive image elements to your site. Picturefill adds support for both the <code>picture</code> element and also new responsive attributes to the <code>img</code> element. You may find that the new <code>img</code> features may be all you need. Let's cover those first.</p>

<p>The <code>sizes</code> syntax is used to define the size of the image across a number of breakpoints. <code>srcset</code> 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 <code>srcset</code> &amp; <code>sizes</code> attributes, so we'd recommend reading the following post by Eric Portis: <ahref="http://ericportis.com/posts/2014/srcset-sizes/">Srcset and Sizes</a>. Read that first, then check out the demos below!</p>

<p>The <code>picture</code> 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. </p>

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

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

<p>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 <code>video</code> element wrapper around the source elements in your <code>picture</code> tag. You can do this using conditional comments, like so:</p>

<p>The <code>1x</code>, <code>2x</code> syntax in <code>srcset</code> acts as a shorthand for more complex resolution media queries. When natively supported, <code>srcset</code> will allow the UA to override requests for higher-resolution options based on a bandwidth limitations or a user preference (see #9 in the <ahref="http://usecases.responsiveimages.org/#h2_requirements">Responsive Images Use Cases and Requirements</a>).</p>

<p>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:</p>

<h3>The picturefill function</h3>

<p>Picturefill.js exposes a single global function: the <code>picturefill()</code> function. <code>picturefill()</code> 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 <code>picturefill()</code> 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:</p>

<pre><code>

picturefill();

</code></pre>

<h3>Picturefill function options</h3>

<p>When running the <code>picturefill()</code> function, you can pass options specifying the following settings:</p>

<ul>

<li><strong>Elements:</strong> An array of <code>img</code> elements you'd like picturefill to evaluate. The Default value for <code>options.elements</code> is all <code>img</code> elements in the page that have a <code>srcset</code> attribute or have a <code>picture</code> element as a direct parent.

<pre><code>picturefill( {

elements: [ document.getElementById( "myPicture" ) ]

} );

</code></pre>

</li>

<li><strong>Reevaluate:</strong> Force picturefill to evaluate all elements in the <code>options.elements</code> array, even if they've already been evaluated. The default is <code>false</code>, except when a resize event triggers Picturefill to run (<code>options.reevaluate</code> is <code>true</code> in that case).

<pre><code>picturefill( {

reevaluate: true

} );

</code></pre>

</li>

</ul>

<h2id="support">Browser Support</h2>

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

<h3id="gotchas">Support caveats to keep in mind</h3>

<p>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:</p>

<ul>

<li><strong>JS-Disabled Browsers only see alt text:</strong> When using the <code>picture</code> element, non-<code>picture</code> supporting browsers will only see <code>alt</code> attribute text as a fallback when JavaScript fails or is disabled. This is because any <code>noscript</code>-based workarounds (such as the one used in Picturefill version 1) will cause future browsers that support the <code>picture</code> element to show two images instead of one when JavaScript is off. Unfortunately, choosing to add a <code>src</code> attribute to the <code>img</code> element in your <code>picture</code> element isn't a good workaround either, as any browser that exists today will fetch that <code>src</code> url even if it is not going to be used (which is wasteful). If you absolutely need an image to appear in non-JS environments, Picturefill 1.2 is a fine choice.</li>

<li><strong>Temporary extra HTTP Requests for Picture usage in some browsers:</strong> In browsers that natively support <code>srcset</code> but do not yet support the <code>picture</code> element, users may experience a wasted HTTP request for each <code>picture</code> element on a page. This is because the browser's preparser will fetch one of the URLs listed in the <code>picture</code> element's child <code>img</code>'s <code>srcset</code> attribute as soon as possible during page load, before the JavaScript can evaluate the potential <code>picture</code> <code>source</code> elements for a better match. This problem will only affect browsers that have implemented <code>srcset</code> but not <code>picture</code>, which will hopefully be short-lived.</li>

<li><strong>Source element limitations:</strong> Browsers like Android 2.3 and Internet Explorer 9 can not see the <code>source</code> elements inside a <code>picture</code> element. For IE, the <code>video</code> tag workaround helps us avoid this problem, but Android will still have no access to <code>source</code> elements. Be sure to provide a <code>srcset</code> attribute on your enclosed <code>img</code> to ensure an image will show in this browser.</li>

<li><strong>Media attribute support requires native media query support</strong>The <code>picture</code> element (paired with picturefill) works best in browsers that support CSS3 media queries. Picturefill includes the <ahref="https://github.com/paulirish/matchMedia.js/">matchMedia polyfill</a> by default, which makes matchMedia work in media query-supporting browsers that don’t support <code>matchMedia</code>.</li>