react-cloudinary-lazy-image

Optimised images with Cloudinary.

'react-cloudinary-lazy-image' is React component which cover "blur-up" effect, lazy-loading and formatting. The component is based on Gatsby image by Kyle Mathew, however instead of GraphQL and Gatsby it uses Cloudinary API. Have a speed and optimized gatsby-images without gatsby.

Covers

1. Downsize larger images to the size needed by your design - even on desktop there is no need to get as big image as possible.
2. Remove metadata from delivered images - by default images contain a lot of information useful for cameras and graphics applications, but not for web users.
3. Format images to newer formats like JPEG-XR and WebP - common formats like PNG, JPG or GIF are not optimised to be send wireless.
4. Lower image quality - many images have extra-high resolution, however it’s possible to lower quality without a significant visual impact.
5. Downsize images on smaller device - display images for mobile users faster as there is probably slower internet connection.
6. Lazy load images - allow images to download only when user scroll to it allows to speed up initial page load.
7. Hold position of element - page doesn’t jump while images load.
8. “Blur-up” technique - show very low resolution image before the original loads.

Points 1-4 are handled by Cloudinary.

Install

npm install react-cloudinary-lazy-image --save

How to use

Fixed example:

import React from 'react'
import Img from 'react-cloudinary-lazy-image'

export default ({publicId}) => (
    <div>
        <h1>Lazy-image with Cloudinary</h1>
        <Img
            cloudName={'cloud'}
            imageName={publicId}
            fixed={{
                width: 300,
                height: 300
            }}
            urlParams={'g_face,c_lfill'}
        />
    </div>
)

Fluid example:

import React from 'react'
import Img from 'react-cloudinary-lazy-image'

export default ({publicId}) => (
    <div>
        <h1>Lazy-image with Cloudinary</h1>
        <Img
            cloudName={'cloud'}
            imageName={publicId}
            fluid={{
                maxWidth: 300,
                height: 300
            }}
            style={{
                width: '40vw',
                height: '20vh'
            }}
        />
    </div>
)

Two types

Same as in gatsby-image there are two types of responsive images. Fixed and fluid.

1. Images with fixed height and width. Cover double pixel density for retina display.
2. Images in fluid container. Takes smallest possible picture to fill container. Configurable step allow you to have control over breakpoints.

Image transformation

You can set image transformation according to Cloudinary documentation, by setting urlParams. You can also find all formats that can be passed to imgFormat prop or get more info about quality prop.

Props

| Name | Type | Description | | ------------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | fixed | object | Object with 'width' and 'height' properties | | fluid | object | Object with 'maxWidth' required property. Optionally step, default=150 and 'height'. If height not set, uses 'c_scale' otherwise 'c_lfill' | | fadeIn | bool | Defaults to fading in the image on load | | cloudName | string | Cloudinary cloud name, default=process.env.CLOUD_NAME or process.env.REACT_APP_CLOUD_NAME | | imageName | string | Cloudinary publicId | | urlParams | string | Cloudinary image transformations params. Overrides default 'c_lfill' or 'c_scale'. If both weight and height (w_, h_) params are set srcSet will not be created.| | title | string | Passed to the img element | | alt | string | Passed to the img element | | style | object | Spread into the default styles of the wrapper element | | imgStyle | object | Spread into the default styles of the actual img element | | placeholderStyle | object | Spread into the default styles of the placeholder img element | | backgroundColor | string / bool | Set a colored background placeholder instead of "blur-up". If true, uses default "lightgray" color. You can also pass in any valid color string. | | onLoad | func | A callback that is called when the full-size image has loaded. | | onError | func | A callback that is called when the image fails to load. | | imgFormat | string / bool | Allow Cloudinary to format image. By default is set to 'f_auto'. Can be switch off by passing 'false' or be formatted to specific format (ex. 'webp') | | quality | string / bool | Allow Cloudinary to change quality of image. By default is set to 'q_auto'. Can be switch off by passing 'false' or to specific value (ex. 'best') | | version | string | Set Cloudinary optional version param. Doc. | | blurSize | number | Width of the low quality image. Default = 20. | | blurUrlParams | string | Cloudinary image transformations params for blur version. | | useUrlParamsToBlur| bool | Flag to use urlParams for blur version. Overrides blurUrlParams. | | IOParams | object | Passed to window.intersectionObserver options. Default: { rootMargin: '200px' } |