next-cloudimage-responsive

v1.2.5

Published

7 months ago

Cloudimage Responsive will smartly resize, compress and accelerate images across the World in your site for all devices. The plugin supports lazy loading technique with fancy animation on image load.

Downloads

659

This plugin detects the width of any image container as well as the device pixel ratio density to load the optimal image size needed. Images are resized on-the-fly via the Cloudimage service, thus offering a comprehensive automated image optimization service.

When an image is first loaded on your website or mobile app, Cloudimage's resizing servers will download the origin image from the source, resize it for the client's screen size and deliver to your users through one or multiple Content Delivery Networks (CDNs). The generated image formats are cached in the CDN and will be delivered rocket fast on any subsequent request.

NOTE: Your original (master) images have to be stored on a server or storage bucket (S3, Google Cloud, Azure Blob...) reachable over HTTP or HTTPS by Cloudimage. If you want to upload your master images to Cloudimage, contact us at [email protected].

Demo

To see the Cloudimage Responsive plugin in action, please check out the Demo page. Play with your browser's window size and observe your Inspector's Network tab to see how Cloudimage delivers the optimal image size to your browser, hence accelerating the overall page loading time.

Responsive plugins family

In order to use Cloudimage responsive plugins on your single-page application, please check out Cloudimage responsive plugins for vanilla Javascript and the most popular Javascript frameworks.

Requirements

To use the Cloudimage Responsive plugin, you will need a Cloudimage token to deliver your images over CDN. Don't worry, it only takes seconds to get one by registering here. Once your token is created, you can configure it as described below. This token allows you to use 25GB of image cache and 25GB of worldwide CDN traffic per month for free.

Step 1: Installation

using npm

$ npm install next-cloudimage-responsive

using yarn

$ yarn add next-cloudimage-responsive

Step 2: Initialize

After installing the next-cloudimage-responsive lib, simply initialize it with your token and the baseURL of your image storage with CloudimageProvider and wrap your application with CloudimageProvider:

import { CloudimageProvider } from 'next-cloudimage-responsive';

function MyApp({ Component, pageProps }) {
  const cloudimageConfig = {
    token: 'demo',
    baseURL: 'https://cdn.scaleflex.it/demo/'
  };

  return (
    <CloudimageProvider config={cloudimageConfig}>
      <Component {...pageProps} />
    </CloudimageProvider>
  );
}

export default MyApp;

Step 3: Implement it

Img component:

import { Img } from 'next-cloudimage-responsive';

<Img src="img.jpg" alt="Demo image"/>

BackgroundImg component:

import { BackgroundImg } from 'next-cloudimage-responsive';

<BackgroundImg src="img.jpg">
 {'Your content...'}
</BackgroundImg>

Config

token

Type: String | Default: "demo" | required

Your Cloudimage customer token. Subscribe for a Cloudimage account to get one. The subscription takes less than a minute and is totally free.

customDomain

Type: String | Default: "cloudimage.io" | optional

If you use a custom CNAME for your cloudimage integration, you can set it here.

Note: this will disregard your token above as this should be built into the CNAME entry.

baseURL

Type: String | Default: "" | optional

Your image folder on server, this alows to shorten your origin image URLs.

apiVersion

Type: String |Default: 'v7' | optional

Allow to use a specific version of API.

set a specific version of API

const cloudimageConfig = {
  token: 'demo',
  baseURL: 'https://cdn.scaleflex.it/demo/',
  apiVersion: 'v7'                            // optional
};

disable API version

const cloudimageConfig = {
  token: 'demo',
  baseURL: 'https://cdn.scaleflex.it/demo/',
  apiVersion: null                            // optional
};

doNotReplaceURL

Type: bool | Default: false

If set to true the plugin will only add query params to the given source of image.

lazyLoading

Type: Bool | Default: true | optional

Only images close to the client's viewport will be loaded, hence accelerating the page loading time. The plugin uses

params

Type: String | Default: 'org_if_sml=1' | optional

Applies default Cloudimage operations/ filters to your image, e.g. brightness, contrast, rotation... Multiple params can be applied, separated by "&" e.g. func=fit&w=400&h=400&bg_colour=f2f7fa

params: 'org_if_sml=1&func=fit&w=400&h=400&bg_colour=f2f7fa'

alternative syntax: type: Object

params: {
    org_if_sml: 1,
    grey: 1,
    ...
}

Full cloudimage v7 documentation here.

server-side rendering (SSR) vs client-side rendering (CSR)

Despite the plugin by default rendering the low-preview image on the server and on the client it renders the optimized image relative to the container size. you can render both low-preview and optimized images on the server-side. by using srr config.

client-side config

limitFactor

Type: Number | Default: 100 | optional

Rounds up the size of an image to the nearest limitFactor value.

For example:

for an image with width 358px and limitFactor equal to 100, the plugin will round up to 400px;
for an image with width 358px and limitFactor equal to 5, the plugin will round up to 360px.

devicePixelRatioList

Type: [Number,...] | Default: [1, 1.5, 2] | optional

List of supported device pixel ratios. If there is no need to support retina devices, you should set an empty array devicePixelRatioList: [].

server-side config

ssr

Type: Boolean | Default: false

Render both low-quality preview and the optimized image on the server. if ssr set to true we can't detect the image container width or the device pixel ratio. so the plugin will generate a srcset relative to device sizes in next.config.js

lowPreviewQuality

Type: Number | Default: 50

The quality of the low-preview image relative to the optimized image.

An integer between 1 and 100, where 100 is best quality.

quality

Type: Number | Default: 75

The quality of the optimized image.

An integer between 1 and 100, where 100 is best quality.

layout

Type: String | Default: responsive

The layout behavior of the image as the viewport changes size.

see layout.

objectFit

Type: String | Default: cover

Defines how the image will fit into its parent container.

see objectFit.

objectPosition

Type: String | Default: center

Defines how the image is positioned within its parent element.

see objectPosition.

transitionDuration

Type: String | Default: 800ms

Defines the transition duration of animation while switching between low-preview image and the optimized image.

NOTE: Set it to 0ms to disable animation.

Image properties

The following config can be used per-image basis.

src

Type: String | Default: undefined | required

Original image hosted on your web server. You can use absolute path or relative to the baseUrl in your config.

NOTES:

The plugin uses a special algorithm to detect the width of image container and set the image size accordingly. This is the recommended way of using the Cloudimage Responsive plugin.

onImgLoad

Type: function | Default: undefined

A function to be executed after the image is loaded

<Img
  src="dino-reichmuth-1.jpg"
  onImgLoad={(event)=>{ console.log(event); }}/>

width

Type: String (e.g. 300px, 20vw) | Default: undefined

If set, the plugin will use the width as a fixed value and change only according to the device pixel ratio. NOTE: while using ssr consider to set a suitable layout to the image.

height

Type: String (e.g. 300px, 20vh) | Default: undefined