VERSIONS

• Low Quality Preview
• Blur Hash
• Plain (CSS free)

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 store your master images with us, you can check our all-in-one Digital Asset Management solution Filerobot.

Table of contents

• Demo
• Responsive plugins family
• Requirements
• Step 1: Installation
• Step 2: Initialize
• Step 3: Implement
• Configuration
• Methods
• Image properties
• Lazy loading
• Process dynamically loaded images
• Browser support
• Filerobot UI Family
• Contributing
• License

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 the most popular Javascript frameworks.

Requirements

Cloudimage account

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.

Layout/CSS

In order to use smooth transition between preview image and good quality and size image, the plugin uses absolute positioning for images and wraps an image tag with a div element with relative positioning.

You have to pay attention to the following things:

• the plugin sets 100% width for the img tag and position:absolute (You should not apply other sizes or change position property. If you need to change the width of an image or its position, you have to set it to the wrapper element)

Step 1: Installation

Add a style tag with CDN link to js-cloudimage-responsive in the head of your site

<link rel="stylesheet" href="https://cdn.scaleflex.it/plugins/js-cloudimage-responsive/latest/js-cloudimage-responsive.min.css?vh=a076ef&func=proxy"></link>

Add a script tag with CDN link to js-cloudimage-responsive

<script src="https://cdn.scaleflex.it/plugins/js-cloudimage-responsive/latest/js-cloudimage-responsive.min.js"></script>

or using npm

$ npm install js-cloudimage-responsive

or using yarn

$ yarn add js-cloudimage-responsive

Step 2: Initialize

After adding the js-cloudimage-responsive library, simply iniatialise it with your token and the baseURL of your image storage:

<script>
    const ciResponsive = new window.CIResponsive({
      token: 'demo',
      baseURL: 'https://cdn.scaleflex.it/demo/' // optional
    });
</script>

or in new style with npm:

import 'js-cloudimage-responsive';

const ciResponsive = new window.CIResponsive({
  token: 'demo',
  baseURL: 'https://cdn.scaleflex.it/demo/' // optional
});

NOTE: You should put the scripts below all your content in the body tag and above all other scripts. After inserting the scripts, the plugin immediately starts processing all images with ci-src and ci-bg-url attributes. (If the scripts are put into the head tag, no images will be detected and processed. If the scripts are put below all other scripts on your page, the images will be not showed until all the scripts are downloaded.)

Step 3: Implement in an img tag or use it as a background image

img tag

Finally, just use ci-src instead of the src attribute in image tag:

<img ci-src="magnus-lindvall.jpg" ci-ratio="1.5"/>

NOTE: setting "ci-ratio" is recommended to prevent page layout jumping. The parameter is used to calculate the image height to hold the image position while the image is loading.

background image

Use ci-bg-url instead of the CSS background-image property background-image: url(...):

<div ci-bg-url="magnus-lindvall.jpg"></div>

Configuration

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.

domain

Type: String | Default: "cloudimg.io"

Use your custom domain.

customDomain

Type: boolean | Default: false | optional

If you use a custom CNAME for your cloudimage integration, set it to true.

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

imgSelector

Type: String | Default: "ci-src"

Cloudimage Responsive Selector for images.

bgSelector

Type: String | Default: "ci-bg-url"

Cloudimage Responsive Selector for background images.

doNotReplaceURL

Type: bool | Default: false

If set to true, the plugin will only add query parameters to the provided image source URL.

baseURL

Type: String | 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

<script>
    const ciResponsive = new window.CIResponsive({
      token: 'demo',
      baseURL: 'https://cdn.scaleflex.it/demo/', // optional
      apiVersion: 'v7'                                       // optional
    });
</script>

• disable API version

<script>
    const ciResponsive = new window.CIResponsive({
      token: 'demo',
      baseURL: 'https://cdn.scaleflex.it/demo/', // optional
      apiVersion: null                                       // optional
    });
</script>

lazyLoading

Type: Bool | Default: false | optional

Only images close to the client's viewport will be loaded, hence accelerating the page loading time. If set to true, an additional script must be included, see Lazy loading

params

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

Applies default Cloudimage operations/filters to your image like brightness, contrast, rotation, etc. Multiple params can be applied, separated by "&" e.g. wat_scale=35&wat_gravity=northeast&wat_pad=10&grey=1

{
 ...,
 params: 'org_if_sml=1'
}

alternative syntax

Type: Object

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

Full cloudimage v7 documentation here.

placeholderBackground

Type: String | Default: '#f4f4f4' | optional

Placeholder coloured background while the image is loading

exactSize

Type: Bool | Default: false | optional

Forces to load exact size of images. By default, the plugin rounds the container width to next possible value which can be divided by 100 without the remainder. This is done for caching reasons so that not all images are cached by 1px, but only 100px, 200px, 300px...

limitFactor

Type: Number | Default: 100 | optional

Rounds up the size of the 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 empty array devicePixelRatioList: []

lowQualityPreview

Type: Object

• lowQualityPreview.minImgWidth number (default: 400) - minimal width of an image to load a low-quality preview image

Example:

lowQualityPreview: {
  minImgWidth = 400
}

presets

Type: Object

Default:

{
    ...,
    presets: {
	xs: '(max-width: 575px)', // up to 575    PHONE
	sm: '(min-width: 576px)', // 576 - 767    PHABLET
	md: '(min-width: 768px)', // 768 - 991    TABLET
	lg: '(min-width: 992px)', // 992 - 1199   SMALL_LAPTOP_SCREEN
	xl: '(min-width: 1200px)' // from 1200    USUALSCREEN
    }
}

Breakpoints shortcuts to use in image size property, can be overridden.

imageSizeAttributes

Type: String | possible values: 'use', 'ignore', 'take-ratio' | Default: 'use'

If width and height attributes are set:

use - width & height attributes values will be used to calculate image size (according to user's DPR) and ratio.

take-ratio - width & height attributes values will be used only to calculate ratio.

ignore - width & height attributes will be ignored.

If width and height attributes are NOT set, image container size will be detected to calculate result image size (according to user's DPR)

Note: If only width or height attributes is set, ratio is going to be taken from ci-ratio image attribute

methods

updateImage

Type: function updateImage(newSrc, imgNode, options)

arguments:

imgNode: HTMLElement The image node to be updated. newSrc: String The new image src. options: Object Options that you need to add on the image, All the image properties can be added in options.

Example:

  const image = document.getElementById('cloudimage-image-example');
  const options = { 'ci-params': 'grey=1', alt: 'dress' };

  window.ciResponsive.updateImage(image, 'dresses-img.jpg', options);

beside using this method to update image src or options. you can use it to for background images.

Example:

  const bgImage = document.getElementById('cloudimage-bg-example');
  const options = { 'ci-params': 'grey=1', alt: 'house' };

  window.ciResponsive.updateImage(bgImage, 'house-img.jpg', options);

addImage

Type: function updateImage(newSrc, imgNode, options)

arguments:

imgNode: HTMLElement The image node to be added.

Supported version: +v4.9.0

Example:

  const image = document.createElement('img');

  image.setAttribute('ci-src', 'dresses-img.jpg');
  image.setAttribute('ci-params', 'gery=1');

  document.body.appendChild(image);
  window.ciResponsive.addImage(image);

beside using this method to update image src or options. you can use it to for background images.

Example:

  const bgImage = document.createElement('section');
  const paragraph = document.createElement('p');

  bgImage.setAttribute('ci-bg-url', 'house-img.jpg');
  bgImage.setAttribute('ci-params', 'gery=1');

  paragraph.innerHTML = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas a nulla dictum';

  bgImage.appendChild(paragraph);
  document.body.appendChild(bgImage);
  window.ciResponsive.addImage(bgImage);

Image properties

The Cloudimage responsive plugin will make an image on your page responsive if you replace the src with a ci-src attribute in the <img> tag:

ci-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 the image container and set the image size accordingly. This is the recommended way of using the Cloudimage Responsive plugin.
• Images where ci-src is not used will be delivered in a standard, non-responsive way.
• Parameters after "?" question mark will be added at the end of result URL after processing by the plugin.

width

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

If it's set, the plugin will use width as a fixed value and change only according device pixel ratio.

height

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

If it's set, the plugin will use height as fixed value and change only according device pixel ratio.

ci-params

Type: String | Default: undefined | optional

You can apply any Cloudimage operations/filters to your image, e.g. brightness, contrast, rotation... Multiple parameters can be applied, separated by "&" e.g. wat_scale=35&wat_gravity=northeast&wat_pad=10&grey=1

ci-params="gray=1&bright=10"

alternative syntax: type: Object

ci-params="{
    bright: 10,
    grey: 1,
    ...
}"

Full cloudimage v7 documentation here.

ci-sizes

Type: Object | Default: undefined

{ preset breakpoint | 'media query': imageProps }:

preset breakpoints: xs, sm, md, lg, xl (can be changed with) imageProps: { w, h, r, src } where

• w - width,
• h - height,
• r - ratio,
• src - original image hosted on your web server. You can use absolute path or relative to the baseURL in your config.

<img
  ci-src="dino-reichmuth-1.jpg"
  ci-sizes="{
     '(max-width: 575px)': { w: 400, h: 150 },
     '(min-width): 576px)': { src: 'dino-reichmuth-square.jpg', r: 1 },
     '(min-width: 620px)': { h: 560 },
     '(min-width: 768px)': { w: '50vw' },
     lg: { w: '55vw', h: 300 },
     xl: { w: 1200 }
 }"/>

You can drop some breakpoints, for example:

<img
  ci-src="dino-reichmuth-1.jpg"
  ci-sizes="{
      sm: { w: 400, h: 200 },
      '(min-width: 620px)': { w: 200, h: 60 }
 }"/>

new experimental syntax

md: { w: '40vw', h: 350 } or md: { w: 250, h: '20vh' }

adds a possibility to use fixed height or width and change the other dimension dynamically

NOTE: if size is not set, 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.

ci-ratio (or data-ci-ratio)

Type: Number | optional

It is recommended to set this parameter to prevent page layout jumping. It is used to calculate the image height to hold the image position while the image is loading.

To see the full Cloudimage documentation, click here.

ci-do-not-replace-url (or data-ci-do-not-replace-url)

Type: Boolean | Default: false | optional

If set to true, the plugin will only add query parameters to the provided image source URL.

ci-not-lazy (or data-ci-not-lazy)

Type: Bool

Switch off lazy loading on a per-image basis.

Lazy Loading

Lazy loading is not included into js-cloudimage-responsive by default. If you enable lazy loading in the configuration, you need to add an additional library.

The example below uses the lazysizes library using Intersection Observer API.

Code Sandbox example

add the following scripts right after js-cloudimage-responsive script

<script>
  window.lazySizesConfig = window.lazySizesConfig || {};
  window.lazySizesConfig.init = false;
</script>
<script src="https://cdn.scaleflex.it/plugins/js-cloudimage-responsive/latest/js-cloudimage-responsive.min.js"></script>
<script src="https://cdn.scaleflex.it/filerobot/js-cloudimage-responsive/lazysizes.min.js"></script>

the initialization script

<script>
    const ciResponsive = new window.CIResponsive({
      token: 'demo',
      baseURL: 'https://cdn.scaleflex.it/demo/', // optional
      lazyLoading: true                                       // optional
    });

    window.lazySizes.init();
</script>

Process dynamically loaded images!

In case you load some images dynamically you need to trigger ciResponsive.process() manually.

<script>
const ciResponsive = new window.CIResponsive({
   token: 'demo',
   baseURL: 'https://cdn.scaleflex.it/demo/', // optional
   lazyLoading: true                                       // optional
});

window.lazySizes.init();

ciResponsive.process(); // -> call when you need to process dynamically loaded images
</script>

The process function accepts a second argument. It expects an HTML Element, if provided it will be used as the root for the images lookup.

Browser support

Tested in all modern browsers and IE 11,10,9.

If you want to address the use case where your visitors disable JS, You have to add a noscript tag:

<noscript><img src="path-to-original-image"/></noscript>

NOTE: If you use lazy loading with IntersectionObserver, you must manually add the IntersectionObserver polyfill for cross-browser support.

Filerobot UI Familiy

• Cloudimage Responsive
• JS Cloudimage 360 view
• Image Editor
• Filerobot Media Asset Widget

Contributing!

All contributions are super welcome!

License

JS Cloudimage Responsive is provided under the MIT License.