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!
@@ -45,8 +45,11 @@
Contributing, Bug Reports, and More
Downloading Picturefill
-
Picturefill Version 3.0.0 (RC 1)
-
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 release candidate is highly welcomed—if you encounter any problems, please file an issue on GitHub.
+
Picturefill Version 3.0.0 (Release Candidate 1)
+
+
Version 3 is a full rewrite of the Picturefill codebase, featuring optimized performance, better emulation of native behavior, and parsers that adhere much more closely to the specification. It also handles many of the quirks, shortcomings, and edge cases related to first-generation native implementations.
+
+
Feedback on this beta release is highly welcomed—if you encounter any problems, please file an issue on GitHub.
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:
+
To start using 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>
@@ -93,7 +96,7 @@
Getting Started with PicturefillMarkup 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.
+
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 picture element and new img element attributes.
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:
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:
-
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 2x source will be shown at the inherent width of the 1x source—so the two sources will occupy the same space in your layout, but the 2x source will be displayed at double the pixel density. This only applies to the natural size of the img—resizing the image via CSS will behave as expected.
-
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.
+
Modern browsers that support srcset 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 2x file may be shown on a 1x device, if that 2x 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.
-
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!
+
Eventually srcset 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 Responsive Images Use Cases and Requirements).
+
+
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.
Using the `srcset` & `sizes` attribut
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">
Standalone srcset and sizes demo
+
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 highly recommend reading the following post by Eric Portis: Srcset and Sizes. Keep in mind that the same caching behavior is applied to this usage of srcset, as well.
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.
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.
+
+
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. Since these image sources are meant to align with layout breakpoints, srcset’s caching behavior and the potential for a bandwidth or user preference override do not apply here.
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:
@@ -175,8 +180,7 @@
Supporting Picture in Internet Explorer 9
`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).
+
The 1x/2x syntax can be used within source element srcset attributes as a shorthand for more complex resolution media queries.
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.
+
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. Unlike existing solutions, the picture element makes these negotiations using a single request.
Picturefill supports SVG and WebP as part of its core, but the following MIME types can be used via the “typesupport” plugin:
When running the picturefill() function, you can pass options specifying the following settings:
+
When running the picturefill() function, you can pass options specifying the following configuration options:
Elements: An array of img elements you'd like picturefill to evaluate. The Default value for options.elements is all img elements in the page that have a srcset attribute or have a picture element as a direct parent.
@@ -244,26 +248,33 @@
Picturefill function options
-
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.
+
Source selection algorithm option
-
To use saveData, create a picturefillCFG array that runs before the main plugin:
+
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 saveData algorithm skews the resource selection algorithm toward smaller image candidates(2x on extremely high dppx devices (3x and up), to conserve bandwidth in situations where there may be little or no visual difference between sources.
+
+
To use saveData, create a picturefillCFG array that runs before the main plugin:
Developer feedback on this new algorithm is welcome, especially if you've got some hard data.
+
Developer feedback on this new algorithm is highly 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.
Browser Support
-
Picturefill supports a broad range of browsers and devices, provided that you stick with the markup conventions documented above.
+
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
+
Support caveats
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:
+
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.
+
+
Picturefill 3 includes a small shim that polyfills common media conditions for IE9 and earlier (min-width, max-width, min-height, and max-height). If you need old IE support for other media conditions, such as orientation or aspect-ratio, please additionally include the matchMedia polyfill.
+
JS-Disabled Browsers only see alt text: When using the picture element, non-picture supporting browsers will only see alt attribute text as a fallback when JavaScript fails or is disabled. This is because any noscript-based workarounds (such as the one used in Picturefill version 1) will cause future browsers that support the picture element to show two images instead of one when JavaScript is off. Unfortunately, adding a src attribute with an external source to the img element in your picture element isn't a good workaround either, as any browser that exists today will fetch that src url even if it is not going to be used (which is wasteful), and an empty src can result in unexpected requests. For valid markup, the shortest possible value for src (without firing an onerror event or a potential request) is
src="data:image/gif;base64,R0lGODlhAQABAAAAADs="
Temporary extra HTTP Requests for picture usage in some browsers: In browsers that natively support srcset but do not yet support the picture element, users may experience a wasted HTTP request for each picture element on a page. This is because the browser's preparser will fetch one of the URLs listed in the picture element's child img's srcset attribute as soon as possible during page load, before the JavaScript can evaluate the potential picturesource elements for a better match. This problem will only affect browsers that have implemented srcset but not picture, which will hopefully be short-lived.
- 
+ 