diff --git a/README.md b/README.md index b032104..e6512bb 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ - [Multi-source configuration](#multi-source-configuration) - [`ix_image_tag`](#iximagetag) - [Fixed image rendering](#fixed-image-rendering) + - [Lazy Loading](#lazy-loading) - [`ix_picture_tag`](#ixpicturetag) - [`ix_image_url`](#iximageurl) - [Usage in Model](#usage-in-model) @@ -179,6 +180,60 @@ https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&w=1000&dpr=5&q= Fixed image rendering will automatically append a variable `q` parameter mapped to each `dpr` parameter when generating a `srcset`. This technique is commonly used to compensate for the increased filesize of high-DPR images. Since high-DPR images are displayed at a higher pixel density on devices, image quality can be lowered to reduce overall filesize without sacrificing perceived visual quality. For more information and examples of this technique in action, see [this blog post](https://blog.imgix.com/2016/03/30/dpr-quality?_ga=utm_medium=referral&utm_source=sdk&utm_campaign=rails-readme). This behavior will respect any overriding `q` value passed in via `url_params` and can be disabled altogether with `srcset_options: { disable_variable_quality: true }`. +#### Lazy loading + +If you'd like to lazy load images, we recommend using [lazysizes](https://github.com/aFarkas/lazysizes). In order to use imgix-rails with lazysizes, you can simply add a `lazy` attribute with `true`: + +```erb +<%= ix_image_tag('image.jpg', lazy: true, url_params: {w: 1000}) %> +``` + +Will render the following HTML: + +```html + +``` + +A small 1x1 GIF will be shown while the image is loading. Once the image +has been loaded in the background, provided you have required lazysizes in your +application, the correct image will be loaded. + +You can optionally pass an image to be used as the loading image: + +```erb +<%= ix_image_tag('image.jpg', lazy: 'loading.gif', url_params: {w: 1000}) %> +``` + +This will render the following HTML: + +```html + +``` + +You can use Imgix for the loading image as long as you use `ix_image_url`: + +```erb +<%= ix_image_tag('image.jpg', lazy: ix_image_url('loading.gif', {w: 1000 }), url_params: {w: 1000}) %> +``` + +Then the result would be: + +```html + +``` + ### `ix_picture_tag` The `ix_picture_tag` helper method makes it easy to generate `picture` elements in your Rails app. `picture` elements are useful when an images needs to be art directed differently at different screen sizes.