316 lines (234 sloc) 27.2 KB
<!DOCTYPE html>
<meta charset=utf-8 />
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href='//|Source+Sans+Pro:400|Source+Sans+Pro:900' rel='stylesheet' type='text/css'>
<link href='examples/styles.css' rel='stylesheet' type='text/css'>
<link href="" rel="icon">
<script async="" src="dist/plugins/intrinsic-dimension/pf.intrinsic.min.js"></script>
<script async="" src="dist/picturefill.min.js"></script>
<nav class="nav">
<li><a href="#download">Download</a></li>
<li><a href="#getting-started">Quickstart</a></li>
<li><a href="#examples">Examples</a></li>
<li><a href="#api">API</a></li>
<li><a href="#support">Support</a></li>
<li><a href="#contributing">Contributing</a></li>
<h1 class="hed">Picturefill</h1>
<p class="subhed">A responsive image polyfill</p>
<a href="" class="ricg-seal">Officially endorsed by the <abbr title="Responsive Issues Community Group">RICG</abbr></a>
<div class="lede">
<p>The <a href=""><code>picture</code> element, <code>srcset</code> and <code>sizes</code> attributes</a>, 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 <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 development is sponsored by <a href=""><img src="logos/fg-sm.png" class="filament-logo inline-logo" alt="Filament Group"></a> and <a href=""><img src="logos/bocoup-sm.png" class="bocoup-logo inline-logo" alt="Bocoup"></a>, and maintained by the <a href="">Picturefill Team</a>. Ongoing discussion of the project is conducted via <a href="">Slack</a>.</p>
<h3 class="hed-subsection" id="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 <a href="">the project on GitHub.</a></p>
<h2 class="hed-section" id="download">Downloading Picturefill</h2>
<h3 class="hed-subsection hed-currentversion">Picturefill Version 3.0.2 (Stable)</h3>
<p>Version 3 is a <em>full rewrite</em> of the Picturefill codebase, featuring optimized performance, better emulation of native behavior, and parsers that adhere much more closely to <a href="">the specification</a>. It also handles many of the quirks, shortcomings, and edge cases related to first-generation native implementations.</p>
<p>Feedback on this release is highly welcomed—if you encounter any problems, please <a href="">file an issue on GitHub</a>.</p>
<a href="" class="download">picturefill.js</a>
<p class="meta">(development version, unminified code)</p>
<a href="" class="download">picturefill.min.js</a>
<p class="meta">(production version, minified code)</p>
<h3 class="hed-subsection">Picturefill Version 2.3.1</h3>
<p>Picturefill 2 is a lightweight polyfill that may not perfectly match native responsive images behavior. Please note however that <a href="">because of a recently-fixed bug</a>, 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 <a href="">matchMedia polyfill</a> for browsers that need it (like IE9).</p>
<a class="download" href="">picturefill.js</a>
<p class="meta">(development version, unminified code)</p>
<a class="download" href="">picturefill.min.js</a>
<p class="meta">(production version, minified code)</p>
<h2 class="hed-section" id="getting-started">Getting Started with Picturefill</h2>
<p>To start using Picturefill download one of the files listed above and reference it from the <code>head</code> section of your HTML document with the following code:</p>
<pre><code>&lt;script src=&quot;picturefill.js&quot;&gt;&lt;/script&gt;</code></pre>
<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 class="hed-subsection">Recommended Usage:</p>
// Picture element HTML5 shiv
document.createElement( &quot;picture&quot; );
&lt;script src=&quot;picturefill.js&quot; async&gt;&lt;/script&gt;
<p class="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>
<h2 class="hed-section" id="examples">Markup Patterns</h2>
<p>Once you've included picturefill.js, you can start adding responsive image elements to your site! Picturefill adds support for the the entire suite of responsive image solutions, including the <code>picture</code> element and new <code>img</code> element attributes.</p>
<p>There are a number of different <a href="">use cases</a> addressed by some combination of features from the <a href="">responsive images specification</a>—here are some of the most common ones:</p>
<nav class="subnav">
<li><a href="#img-srcset">I want to serve high-res assets only to users with high pixel density viewports</a></li>
<li><a href="#img-sizes">I want the browser to choose the best image source for a user’s pixel density <em>and</em> the size of the image in the layout.</li>
<li><a href="#using-picture">I need my image sources to change only at specific breakpoints that I define.</a></li>
<li><a href="#using-media-and-srcset">I need specific image breakpoints, with multiple resolution options for each.</a></li>
<li><a href="#using-type">I want to serve newer image formats only to browsers that support them.</a></li>
<h3 class="hed-pattern" id="img-srcset">Using the `srcset` attribute</h3>
<p class="usecase">The <code>srcset</code> attribute (without <code>sizes</code>) is used to serve larger—but otherwise identical—image sources to high resolution displays only.</p>
<pre><code>&lt;img srcset=&quot;examples/images/image-384.jpg 1x, examples/images/image-768.jpg 2x&quot; alt=&quot;&quot;&gt;</code></pre>
<p>Here's how that renders on your display:</p>
<img srcset="examples/images/image-384.jpg 1x, examples/images/image-768.jpg 2x" alt="A giant stone face at The Bayon temple in Angkor Thom, Cambodia">
<p>If the <a href="dist/plugins/intrinsic-dimension/">intrinsic dimension plugin</a> is installed: The <code>2x</code> source will be automatically scaled down by 2 — so that the image will occupy the same space in your layout as the <code>1x</code>, but the <code>2x</code> source will be displayed at double the pixel density. This only applies to the <em>natural</em> size of the <code>img</code>—resizing the image via CSS or with the <code>width</code> content attribute will behave as expected.</p>
<p class="note" id="caching">Modern browsers that support <code>srcset</code> natively may select a cached file that meets the minimum media condition, even if it is “overkill” for the current media condition. For example, a <code>2x</code> file may be shown on a <code>1x</code> device, if that <code>2x</code> file is already in the cache—there’d be no reason to make an additional request when the user will see no discernable difference, after all. This is typically encountered only on sites with multiple versions of the same image displayed in multiple elements at different sizes (like our demo page). The occasional selection of "oversize" resources—depending on the cache—is currently an expected behavior in native implementations and you may encounter it during testing.</p>
<p id="override">Eventually <code>srcset</code> will be extended to allow the browser to override requests for higher-resolution options based on a bandwidth limitations or a user preference (see #9 in the <a href="">Responsive Images Use Cases and Requirements</a>).</p>
<h3 class="hed-pattern" id="img-sizes">Using the `srcset` &amp; `sizes` attributes</h3>
<p class="usecase">The <code>srcset</code> and <code>sizes</code> 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.</p>
sizes=&quot;(min-width: 40em) 80vw, 100vw&quot;
srcset=&quot;examples/images/medium.jpg 375w,
examples/images/large.jpg 480w,
examples/images/extralarge.jpg 768w&quot;
<p>Here's how that renders on your display at your current viewport size:</p>
<img sizes="(min-width: 40em) 80vw, 100vw"
srcset="examples/images/medium.jpg 375w, examples/images/large.jpg 480w, examples/images/extralarge.jpg 768w" alt="A giant stone face at The Bayon temple in Angkor Thom, Cambodia">
<a href="examples/demo-01.html" class="demo">Standalone <code>srcset</code> and <code>sizes</code> demo</a>
<p>The <code>sizes</code> syntax is used to define the spaces your image will occupy in your layout. <code>srcset</code> then defines a list of images and their inherent widths. This allows the browser to choose the smallest appropriate source for the size <em>available in that part of the layout</em>, rather than the viewport size alone.</p>
<p>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 highly recommend reading the following post by Eric Portis: <a href="">Srcset and Sizes</a>. Keep in mind that the same <a href="#caching">caching behavior</a> is applied to this usage of <code>srcset</code>, as well.</p>
<h3 class="hed-pattern" id="using-picture">Using the `picture` element</h3>
<p class="usecase">The <code>picture</code> element is used when you need explicit control over which source is shown at set viewport sizes.</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 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 <code>alt</code> attribute of the inner <code>img</code>.</p>
&lt;source srcset=&quot;examples/images/extralarge.jpg&quot; media=&quot;(min-width: 1000px)&quot;&gt;
&lt;source srcset=&quot;examples/images/art-large.jpg&quot; media=&quot;(min-width: 800px)&quot;&gt;
&lt;img srcset=&quot;examples/images/art-medium.jpg&quot; alt=&quot;&quot;&gt;
<p>Here's how that renders at your current viewport size:</p>
<source srcset="examples/images/extralarge.jpg" media="(min-width: 1000px)">
<source srcset="examples/images/art-large.jpg" media="(min-width: 600px)">
<img srcset="examples/images/art-medium.jpg" alt="A giant stone face at The Bayon temple in Angkor Thom, Cambodia">
<a href="examples/demo-02.html" class="demo">Standalone <code>picture</code> demo</a>
<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>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. Since these image sources are meant to align with layout breakpoints, <code>srcset</code>’s <a href="#caching">caching behavior</a> and the potential for a <a href="#override">bandwidth or user preference override</a> do not apply here.</p>
<h3 class="hed-subsection" id="ie9">Supporting Picture in Internet Explorer 9</h3>
<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>
&lt;!--[if IE 9]&gt;&lt;video style=&quot;display: none;&quot;&gt;&lt;![endif]--&gt;
&lt;source srcset=&quot;examples/images/extralarge.jpg&quot; media=&quot;(min-width: 1000px)&quot;&gt;
&lt;source srcset=&quot;examples/images/large.jpg&quot; media=&quot;(min-width: 800px)&quot;&gt;
&lt;!--[if IE 9]&gt;&lt;/video&gt;&lt;![endif]--&gt;
&lt;img srcset=&quot;examples/images/medium.jpg&quot; alt=&quot;&quot;&gt;
<h3 class="hed-subsection" id="fowi-safari">Preventing the Flash of Wrong Image™ on Safari</h3>
<p>Sometimes when using picturefill in Safari, the wrong image may briefly load before the correct source had been chosen. We call this the Flash of Wrong Image™. The only way to prevent this is by removing the <code>src</code> and <code>srcset</code> on the fallback image. <em>It's important to note, however, that this may cause the image from displaying on old android devices (2.3)</em>.</p>
&lt;!--[if IE 9]&gt;&lt;video style=&quot;display: none;&quot;&gt;&lt;![endif]--&gt;
&lt;source srcset=&quot;examples/images/extralarge.jpg&quot; media=&quot;(min-width: 1000px)&quot;&gt;
&lt;source srcset=&quot;examples/images/large.jpg&quot; media=&quot;(min-width: 800px)&quot;&gt;
&lt;!--[if IE 9]&gt;&lt;/video&gt;&lt;![endif]--&gt;
&lt;img alt=&quot;&quot;&gt;
<h3 class="hed-subsection" id="using-media-and-srcset">`media` and `srcset` syntax:</h3>
<p>The <code>1x</code>/<code>2x</code> syntax can be used within <code>source</code> element <code>srcset</code> attributes as a shorthand for more complex resolution media queries.</p>
&lt;source srcset=&quot;examples/images/large.jpg, examples/images/extralarge.jpg 2x&quot; media=&quot;(min-width: 800px)&quot;&gt;
&lt;img srcset=&quot;examples/images/small.jpg, examples/images/medium.jpg 2x&quot; alt=&quot;&quot;&gt;
<!--[if IE 9]><video style="display: none;"><![endif]-->
<source srcset="examples/images/large.jpg, examples/images/extralarge.jpg 2x" media="(min-width: 800px)">
<!--[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">
<a href="examples/demo-03.html" class="demo">Standalone extended <code>picture</code> demo</a>
<h3 class="hed-pattern" id="using-type">The `type` attribute in `picture`</h3>
<p class="usecase">The <code>types</code> attribute is used to send an alternate image source <em>format</em> only to browsers that support that format, and a fallback source to browsers that do not. Unlike <a href="">existing solutions</a>, the <code>picture</code> element makes these negotiations using a single request.</p>
<p>Picturefill supports SVG and WebP as part of its core, but the following MIME types can be used via the “typesupport” plugin:</p>
&lt;source srcset=&quot;examples/images/large.webp&quot; type=&quot;image/webp&quot;&gt;
&lt;img srcset=&quot;examples/images/large.jpg&quot; alt=&quot;&quot;&gt;
<p>Here's how that renders in your browser:</p>
<source srcset="examples/images/large.webp" type="image/webp">
<img srcset="examples/images/large.jpg" alt="A giant stone face at The Bayon temple in Angkor Thom, Cambodia">
<a href="examples/demo-04.html" class="demo">Standalone <code>type</code> attribute demo</a>
<h2 class="hed-section" id="api">Picturefill JavaScript API</h2>
<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 class="hed-pattern">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>
<h3 class="hed-subsection">Picturefill function options</h3>
<p>When running the <code>picturefill()</code> function, you can pass options specifying the following configuration options:</p>
<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.
elements: [ document.getElementById( "myImg" ) ]
<li><strong>Reevaluate:</strong> If you dynamically change the <code>srcset</code>, <code>sizes</code> attributes, or modify <code>source</code> elements, please use this reevaluate option and provide an array or array-like object of your mutated <code>img</code> elements. As an alternative the <a href="dist/plugins/mutation/pf.mutation.js">mutation plugin</a> can be used.
reevaluate: true,
elements: [ document.getElementById( "myImg" ) ]
<h3 class="hed-subsection">Picturefill plugins/extensions</h3>
<p>Picturefill core polyfills the core part of responsive images, including full support for <code>srcset</code>, <code>sizes</code> and <code>picture</code>/<code>source</code>.</p>
<p>Some aspects of the native feature are left out to provide a clean and lightweight polyfill. In case you need a specific behavior of the native implementation not included in picturefill core, just add the corresponding plugin. The best way is to merge all scripts together.</p>
<li><strong><a href="dist/plugins/intrinsic-dimension/">intrinsic dimension</a></strong>: This extension adds support for intrinsic dimension behavior of responsive images. It's useful when you don't style your images with CSS.</li>
<li><strong><a href="dist/plugins/mutation/">Mutation plugin</a></strong>: This plugin automatically detects any DOM mutation and polyfills new or changed responsive images automatically. It also adds support for responsive images IDL attributes/properties. If you have a highly dynamic website or a SPA you probably want to use this plugin. (This plugin does not work with IE8.)</li>
<li><strong><a href="dist/plugins/typesupport/">Type support</a></strong>: This plugin extends support for the <code>source[type]</code> attribute and detects JPG2000, APNG and JPEG XR support. If you want to use new image formats you probably want to use this plugin.</li>
<li><strong><a href="dist/plugins/oldie/">OldIE (IE6/7)</a></strong>: picturefill supports most browsers including IE8+. In case you need to support IE6/7, you can combine the oldIE plugin with jQuery to add support for these browsers.</li>
<h3 class="hed-subsection">Source selection algorithm option</h3>
<p>By default Picturefill attempts to mimic the resource selection algorithms current native implementations, but Picturefill 3 also includes an optional and experimental custom source selection algorithm. The <code>saveData</code> algorithm skews the resource selection algorithm toward smaller image candidates(<code>2x</code> on extremely high dppx devices (<code>3x</code> and up), to conserve bandwidth in situations where there may be little or no <em>visual</em> difference between sources.</p>
<p>To use <code>saveData</code>, create a <code>picturefillCFG</code> array that runs before picturefill:
<pre><code>//generating the config array
window.picturefillCFG = window.picturefillCFG || [];
picturefillCFG.push([ "algorithm", "saveData" ]);</pre></code>
<p>Developer feedback on this new algorithm is <em>highly</em> welcomed. We’d love to see some data around potential bandwidth savings, and this data may go on to inform native responsive image implementations in the future.</p>
<h2 class="hed-section" id="support">Browser Support</h2>
<p>Picturefill supports a broad range of browsers and devices, provided that you stick with the markup conventions documented above.</p>
<!--<h3 class="hed-subsection" id="markup-conventions">Markup Conventions</h3>-->
<!-- TODO: Detail trade-offs of various markup/fallback patterns. -->
<h3 class="hed-subsection" id="gotchas">Support caveats</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>
<li>Picturefill 3 includes a small shim that polyfills common media conditions for IE9 and earlier (<code>min-width</code>, <code>max-width</code>, <code>min-height</code>, and <code>max-height</code>). If you need old IE support for other media conditions, such as <code>orientation</code> or <code>aspect-ratio</code>, please additionally include the <a href="">matchMedia polyfill</a>.</li>
<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, adding a <code>src</code> attribute with an external source 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), and an empty <code>src</code> can result in <a href="">unexpected requests</a>. For valid markup, the shortest possible value for <code>src</code> (without firing an <code>onerror</code> event or a potential request) is <pre><code>src="data:image/gif;base64,R0lGODlhAQABAAAAADs="</pre></code></li>
<li><strong>Temporary extra HTTP Requests for <code>picture</code> 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 <a href="">matchMedia polyfill</a> by default, which makes matchMedia work in media query-supporting browsers that don’t support <code>matchMedia</code>.</li>
<footer class="foot">
<h2 class="hed-sponsors">Sponsors</h2>
<div class="sponsors">
<a href=""><img class="spon-fg" src="logos/fg-lg.png"></a>
<a href=""><img class="spon-bocoup" src="logos/bocoup-lg.png"></a>