plastic-image - Vaadin Add-on Directory

# \ A Polymer 3.0 element which adds extra plasticity to `iron-image` with support for **srcset**, **lazy loading** and **webp**. `plastic-image` extends `iron-image` by adding a `srcset` attribute for client side image size selection. It adds a `lazy-load` attribute for deferring the image load until the element is showing in the viewport. Finally, it allows you to serve (typically smaller) `webp` images to browsers that support webp. Please review the api docs for `iron-image` as this element is a subclass of `iron-image`. ## Available Versions **1.0.14** is the latest version for Polymer **2.0** and can be installed via **bower**: ``` bower install --save plastic-image#1.0.14 ``` ***3.0.0*** is the version for Polymer **3.0** and can be installed via **npm**: ``` npm install --save plastic-image ``` ## plastic-image srcset The `srcset` attribute is a string consisting of one or more image selection strings separated by commas. Each image selection string is composed of: 1. A url to an image 2. One or more spaces as a separator 3. One or _more_ descriptors separated by spaces - width descriptor: a positive integer directly followed by 'w'. e.g. `700w` - height descriptor: a positive integer directly followed by 'h'. e.g. `345h` - pixel density descriptor: a positive floating point number directly followed by 'x'. e.g. `2.0x` `plastic-image` extends the `` feature by allowing multiple descriptors for an image and mixed descriptors in a single srcset. `plastic-image` also extends srcset use by optionally allowing image selection to be based on the render size of the `plastic-image` element instead of the viewport, which is the standard. To use this optional function include the `use-element-dim` attribute. ### Example srcset `srcset="foo-s.jpg 150w, foo-sh.jpg 150w 2.0x, foo-m.jpg 405w, foo-mh 2.0x 405w, foo-l 1024w, foo-t 500w 750h"` ### Automatic Density If _none_ of the image selection strings includes a pixel density descriptor ('x' e.g. `4.0x`), then the image selection process will automatically compensate for the viewport's pixel density. ## Lazy ... wait for it ... Loading Lazy loading delays loading the image (but not the placeholder image) until the element is at least 1px inside the viewport. This can improve the perceived performance of the page by removing below the fold images from first paint. `plastic-image` uses an `IntersectionObserver` to trigger image loads when `lazy-load` is selected. IntersectionObserver is automatically polyfilled if a feature test shows the browser does not include native support. To use lazy loading simply add the `lazy-load` attribute to the element. ```HtML ``` ## Webp Support You can include `webp` format images alongside images of other formats (e.g. JPG, GiF, PNG) in the `srcset` attribute. If you include one or more webp images and the browser supports webp, the control will select the best fit webp image. If the browser does not support webp, the control will select the best fit non webp image. Webp images are typically significantly smaller than JPG or PNG so it can represent a decrease in network traffic. There are no flags to enable this support. Just include webp along with non webp images in the srcset to take advantage. ### How Webp Images are Detected in the srcset `plastic-image` checks for webp images using a regular expression. The default regex is `/\.webp$/i` (i.e. the url ends with `.webp`). This may not work for you if you are using url parameters or if for any other reason the url doesn't end with `.webp`. You can modify the regex used to suit your url scheme by setting the `webpRegex` property: ```HTML ``` ## Install the Component For Polymer 3.0: ``` npm install --save plastic-image ``` For Polymer 2.0: ``` bower install --save plastic-image#1.0.14 ``` ## Basic Use Examples Use the control as you would an `iron-image` but with the srcset. ```HTML ``` To base image selection on the rendered size of the control, instead of the viewport (default), add the `use-element-dim` attribute. ```HTML ``` To automatically compensate for pixel density do not supply _any_ pixel density descriptors in the srcset. ```HTML ``` To defer loading until the image is in (well, at least peaking into) the viewport add the `lazy-load` attribute. ```HTML ``` To serve webp images to browsers that support webp and jpg to browsers that do not, simply include the alternate webp images in the srcset. You can mix in width, height and density selectors also. ```HTML ``` If you need to control when to load (perhaps you are waiting for an ajax response) use the `delay-load` attribute and then set `delayLoad` to false once your data is ready. ```HTML ``` ```Javascript fetch('imageDetail/47561').then((response) => { return response.json(); }).then((imgData) => { this.myImageSelector = imgData.srcset; this.myMicroB64 = imgData.mt; this.$.foo.delayLoad = false; }); ``` ## Polymer Build / polymer.json The element may automaticall loads a polyfill script to support IntersectionObserver on browsers where native support is not available. The script is not detected by the Polymer build analyzer. If you are using `polymer build` you should modify the `polymer.json` file to include the script in your build by adding them to the `extraDependencies` array: ```Javascript "extraDependencies": [ "node_modules/plastic-image/intersection-observer.js", ... ] ``` or, on Polymer 2.0: ```Javascript "extraDependencies": [ "bower_components/plastic-image/intersection-observer.js", ... ] ``` ## Standard iron-image properties that should not be used Do not use `preventLoad` / `prevent-load`. This is used internally by `plastic-image` to allow the srcset processing step. To achieve that function use `delayLoad` / `delay-load` instead. Do not use `src`. That will be overwritten by the srcset evaluation. To specify a fallback image use the `fallbackSrc` / `fallback-src` attribute instead. ## License MIT