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.
npm install js-cloudimage-responsive





alt="cloudimage logo"
src="https://scaleflex.cloudimg.io/v7/cloudimage.io/LOGO+WITH+SCALEFLEX-01.png?vh=f6080d&w=350">
alt="cloudimage logo"
src="https://scaleflex.cloudimg.io/v7/cloudimage.io/cloudimage-logo-light.png?vh=b798ab&w=350">
Docs
•
Documentation for v2 | Cloudimage v6
•
Demo
•
Code Sandbox
•
Why?
alt="The Lounge"
src="https://cdn.scaleflex.it/filerobot/cloudimage-process.jpg">
javascript
`
Add a script tag with CDN link to js-cloudimage-responsive
`javascript
`
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:
`javascript
`
or in new style with npm:
`javascript
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
$3
Finally, just use ci-src instead of the src attribute in image tag:
`html
`
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.
$3
Use ci-bg-url instead of the CSS background-image property background-image: url(...):
`html
`
Configuration
$3
###### 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.
$3
###### Type: String | Default: "cloudimg.io"
Use your custom domain.
$3
###### 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.
$3
###### Type: String | Default: "ci-src"
Cloudimage Responsive Selector for images.
$3
###### Type: String | Default: "ci-bg-url"
Cloudimage Responsive Selector for background images.
$3
###### Type: bool | Default: false
If set to true, the plugin will only add query parameters to the provided image source URL.
$3
###### Type: String | _optional_
Your image folder on server; this alows to shorten your origin image URLs.
$3
###### Type: String |Default: 'v7' | _optional_
Allow to use a specific version of API.
- set a specific version of API
`javascript
`
- disable API version
`javascript
`
$3
###### 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
$3
###### 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
`javascript
{
...,
params: 'org_if_sml=1'
}
`
#### alternative syntax
###### Type: Object
`javascript
{
...,
params: {
org_if_sml: 1,
grey: 1,
...
}
}
`
Full cloudimage v7 documentation here.
$3
###### Type: String | Default: '#f4f4f4' | _optional_
Placeholder coloured background while the image is loading
$3
###### 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...
$3
###### 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.
$3
###### 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: []
$3
###### Type: Object
* lowQualityPreview.minImgWidth number (default: 400) - minimal width of an image to load a low-quality preview image
Example:
`javascript
lowQualityPreview: {
minImgWidth = 400
}
`
$3
###### Type: Object
Default:
`javascript
{
...,
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.
$3
###### 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:
`js
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:
`js
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:
`js
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:
`js
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 tag:
$3
###### 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.
$3
###### 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.
$3
###### 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.
$3
###### 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
`javascript
ci-params="gray=1&bright=10"
`
#### alternative syntax: type: Object
`javascript
ci-params="{
bright: 10,
grey: 1,
...
}"
`
Full cloudimage v7 documentation here.
$3
###### 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.
`jsx
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:
`jsx
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.
$3
###### 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.
$3
###### Type: Boolean | Default: false | _optional_
If set to true, the plugin will only add query parameters to the provided image source URL.
$3
###### 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
`javascript
`
the initialization script
`javascript
`
Process dynamically loaded images!
In case you load some images dynamically you need to trigger ciResponsive.process() manually.
`javascript
`
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:
`html
``