Skip to content
This repository
Fetching contributors…

Cannot retrieve contributors at this time

file 233 lines (177 sloc) 18.729 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233
<!DOCTYPE html>
<html>
<head>
<meta charset=utf-8 />
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Picturefill</title>
<link href='http://fonts.googleapis.com/css?family=Raleway' rel='stylesheet' type='text/css'>
<link href='http://fonts.googleapis.com/css?family=Source+Sans+Pro:400' rel='stylesheet' type='text/css'>
<link href='examples/styles.css' rel='stylesheet' type='text/css'>
<link href="https://raw.githubusercontent.com/ResponsiveImagesCG/responsiveimages.org/master/img/favicon.ico" rel="icon">
<script>
// Picture element HTML shim|v it for old IE (pairs with Picturefill.js)
document.createElement( "picture" );
</script>
<script async="true" src="dist/picturefill.js"></script>
</head>
<body>
<a href="http://responsiveimages.org/" class="ricg"><img src="https://raw.github.com/ResponsiveImagesCG/meta/master/logo/Web/RICG_logo_small.png"></a>
<h1>Picturefill <em>A responsive image polyfill</em></h1>

<nav>
<ul class="nav">
<li><a href="#download">Download</a></li>
<li><a href="#getting-started">Getting Started</a></li>
<li><a href="#examples">Examples</a></li>
<li><a href="#api">API</a></li>
<li><a href="#support">Browser support</a></li>
<li><a href="#contributing">Contributing</a></li>
</ul>
</nav>

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

<h3 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 the the code project site on Github : <a href="https://github.com/scottjehl/picturefill">Picturefill on Github.</a></p>

<h2 id="download">Downloading Picturefill</h2>
<h3>Picturefill Version 2.1.0 (Beta)</h3>
<p>For native <code>picture</code> element support, you'll want Picturefill version 2. These downloads include the <a href="https://github.com/paulirish/matchMedia.js/">matchMedia polyfill</a> for browsers that need it (like IE9).</p>
<ul>
<li><a href="https://github.com/scottjehl/picturefill/blob/2.1.0-beta/dist/picturefill.js">picturefill.js</a> (development version, unminified code)</li>
<li><a href="https://github.com/scottjehl/picturefill/blob/2.1.0-beta/dist/picturefill.min.js">picturefill.min.js</a> (production version, minified code)</li>
</ul>
<h3>Version 1.2.1 (latest stable version)</h3>
<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><a href="https://github.com/scottjehl/picturefill/blob/1.2.1/picturefill.js">Picturefill version 1.2.1</a></li>
<li><a href="https://github.com/scottjehl/picturefill/blob/1.2.1/README.md">Version 1.2.1 readme</a></li>
</ul>


<h2 id="getting-started">Getting Started with Picturefill Version 2</h2>

<p>For basic usage of 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><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>

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

<h3 id="img-sizes">Using <code>img</code> with <code>srcset</code> &amp; <code>sizes</code> attributes</h3>

<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: <a href="http://ericportis.com/posts/2014/srcset-sizes/">Srcset and Sizes</a>. Read that first, then check out the demos below!</p>

<h3>An img with "srcset" and sizes" attributes:</h3>
<pre><code>&lt;img sizes=&quot;(min-width: 40em) 80vw, 100vw&quot;
srcset=&quot;examples/images/medium.jpg 375w, examples/images/medium.jpg 480w, examples/images/large.jpg 768w&quot; alt=&quot;A giant stone face at The Bayon temple in Angkor Thom, Cambodia&quot;&gt;
</code></pre>

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

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

<p><a href="examples/demo-01.html">View standalone demo</a></p>

<h2 id="using-picture">Using the <code>picture</code> element</h2>

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

<pre><code>&lt;picture&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;source srcset=&quot;examples/images/medium.jpg&quot;&gt;
&lt;img srcset=&quot;examples/images/medium.jpg&quot; alt=&quot;A giant stone face at The Bayon temple in Angkor Thom, Cambodia&quot;&gt;
&lt;/picture&gt;
</code></pre>

<h3 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>

<pre><code>&lt;picture&gt;
&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;source srcset=&quot;examples/images/medium.jpg&quot;&gt;
&lt;!--[if IE 9]&gt;&lt;/video&gt;&lt;![endif]--&gt;
&lt;img srcset=&quot;examples/images/medium.jpg&quot; alt=&quot;A giant stone face at The Bayon temple in Angkor Thom, Cambodia&quot;&gt;
&lt;/picture&gt;
</code></pre>

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

<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)">
<source srcset="examples/images/medium.jpg">
<!--[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>

<p><a href="examples/demo-02.html">View standalone demo</a></p>

<h2>More Picture markup examples</h2>

<h3 id="media-and-srcset"><code>media</code> and <code>srcset</code> syntax:</h3>
<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 <a href="http://usecases.responsiveimages.org/#h2_requirements">Responsive Images Use Cases and Requirements</a>).</p>

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

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

<p><a href="examples/demo-03.html">View standalone demo</a></p>

<h3 id="types"><code>media</code> example with one webp source qualified with a <code>type</code> attribute.</h3>
<p>Note: Picturefill supports SVG and WebP types on any source element, and will disregard a <code>source</code> if its type is not supported in a particular environment:</p>

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

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

<p><a href="examples/demo-04.html">View standalone demo</a></p>

<h2 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>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>picture</code> and <code>img[srcset]</code> elements you'd like picturefill to evaluate. The Default value for <code>options.elements</code> is all <code>picture</code> and <code>img[srcset]</code> elements in the page.
<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>

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


<h3 id="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 <a href="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>
</ul>

</body>
</html>
Something went wrong with that request. Please try again.