Adaptive
Generate responsive HTML picture elements powered by on-the-fly Filestack image conversions.
Install / Use
/learn @filestack/AdaptiveREADME
Table of Contents
<!-- toc -->What is Adaptive
Adaptive is a tool which allow Filestack users to combine the power of on-the-fly image processing with the latest standard for responsive web images.
This library ships with a built-in virtual DOM adapter powered by hyperx, which allows you to simply call picture(source, options, renderer), where renderer can be any DOM builder supported by hyperx (e.g React.createElement). If renderer is not provided then picture will default to returning plain DOM.
Features
- Focus on usability and performance
- Works with Filestack handles, storage aliases and external urls
- Support for different sizes and formats in srcSet
- Allows you to add some image transformations
- Easily integrable with external virtual DOM renderers
Usage
Browser
You can find the newest version at https://static.filestackapi.com/adaptive/1.4.0/adaptive.min.js <br>
<script src="https://static.filestackapi.com/adaptive/1.4.0/adaptive.min.js" crossorigin="anonymous"></script>
<script>
const options = {
alt: 'windsurfer',
sizes: {
fallback: '60vw',
}
};
const el = fsAdaptive.picture(FILESTACK_HANDLE, options);
document.body.appendChild(el);
</script>
Output:
<picture>
<img src="https://cdn.filestackcontent.com/5aYkEQJSQCmYShsoCnZN"
srcset="
https://cdn.filestackcontent.com/resize=width:180/5aYkEQJSQCmYShsoCnZN 180w,
https://cdn.filestackcontent.com/resize=width:360/5aYkEQJSQCmYShsoCnZN 360w,
https://cdn.filestackcontent.com/resize=width:540/5aYkEQJSQCmYShsoCnZN 540w,
https://cdn.filestackcontent.com/resize=width:720/5aYkEQJSQCmYShsoCnZN 720w,
https://cdn.filestackcontent.com/resize=width:900/5aYkEQJSQCmYShsoCnZN 900w,
https://cdn.filestackcontent.com/resize=width:1080/5aYkEQJSQCmYShsoCnZN 1080w,
https://cdn.filestackcontent.com/resize=width:1296/5aYkEQJSQCmYShsoCnZN 1296w,
https://cdn.filestackcontent.com/resize=width:1512/5aYkEQJSQCmYShsoCnZN 1512w,
https://cdn.filestackcontent.com/resize=width:1728/5aYkEQJSQCmYShsoCnZN 1728w,
https://cdn.filestackcontent.com/resize=width:1944/5aYkEQJSQCmYShsoCnZN 1944w,
https://cdn.filestackcontent.com/resize=width:2160/5aYkEQJSQCmYShsoCnZN 2160w,
https://cdn.filestackcontent.com/resize=width:2376/5aYkEQJSQCmYShsoCnZN 2376w,
https://cdn.filestackcontent.com/resize=width:2592/5aYkEQJSQCmYShsoCnZN 2592w,
https://cdn.filestackcontent.com/resize=width:2808/5aYkEQJSQCmYShsoCnZN 2808w,
https://cdn.filestackcontent.com/resize=width:3024/5aYkEQJSQCmYShsoCnZN 3024w"
alt="photo_01"
sizes="60vw">
</picture>
SRI
Subresource Integrity (SRI) is a security feature that enables browsers to verify that files they fetch (for example, from a CDN) are delivered without unexpected manipulation. It works by allowing you to provide a cryptographic hash that a fetched file must match
To obtain sri hashes for adaptive library check manifest.json file on CDN:
https://static.filestackapi.com/adaptive/{LIBRARY_VERSION}/manifest.json
<script src="//static.filestackapi.com/adaptive/{LIBRARY_VERSION}/adaptive.min.js" integrity="{FILE_HASH}" crossorigin="anonymous"></script>
Where {LIBRARY_VERSION} is currently used library version and {FILE_HASH} is one of the hashes from integrity field in manifest.json file
Node (react example)
npm install filestack-adaptive
import react from 'react';
import reactDOM from 'react-dom';
import { picture } from 'filestack-adaptive';
// Need to spread children parameter to prevent React key warnings
const createElement = (Component, props, children) => {
return React.createElement(Component, props, ...children);
};
const options = { alt: 'windsurfer', sizes: { fallback: '100vw' } };
const tree = picture(FILESTACK_HANDLE, options, createElement);
ReactDOM.render(tree, document.body);
Use with JSX
In a case of need to create your own <picture/> element you can call makePictureTree directly in your JSX
import React, { Component } from 'react';
import { makePictureTree } from 'filestack-adaptive';
class Picture extends Component {
renderSources(sources) {
return sources.map((sourceObj) => {
return <source {...sourceObj} />;
});
}
renderImage(imageObj) {
return <img {...imageObj} />;
}
render() {
const tree = makePictureTree(this.props.handle, this.props);
return (
<picture>
{tree.sources && this.renderSources(tree.sources)}
{this.renderImage(tree.img)}
</picture>
);
}
}
export default Picture;
Storage aliases and external urls
You can also use Filestack storage alias or external urls as an image source:
<script src="https://static.filestackapi.com/adaptive/1.4.0/adaptive.min.js"></script>
<script>
const options = {
alt: 'windsurfer',
sizes: {
fallback: '60vw',
}
};
const srcHandle1 = {
srcHandle: 'src://your_storage_alias_name/example.jpg',
apiKey: 'YOUR_FILESTACK_API_KEY'
};
const el1 = fsAdaptive.picture(srcHandle1, options);
document.body.appendChild(el1);
const srcHandle2 = {
srcHandle: 'https://yourdomain.com/photo1.jpg,
apiKey: 'YOUR_FILESTACK_API_KEY'
};
const el2 = fsAdaptive.picture(srcHandle2, options);
document.body.appendChild(el2);
</script>
Image width and pixel density
When the image width is known it will generate a srcset for HiDPI screens at 2x. More densities can be specified
by passing an array to the resolutions option, e.g. resolutions: ['1x', '2x', '3x'].
const options = {
alt: 'windsurfer',
width: '768px',
};
picture(FILESTACK_HANDLE, options);
Output:
<picture>
<img src="https://cdn.filestackcontent.com/resize=width:768/5aYkEQJSQCmYShsoCnZN"
srcset="https://cdn.filestackcontent.com/resize=width:768/5aYkEQJSQCmYShsoCnZN 1x,
https://cdn.filestackcontent.com/resize=width:1536/5aYkEQJSQCmYShsoCnZN 2x"
alt="windsurfer"
width="768">
</picture>
Webcomponent
Adaptive now supports webcomponent. Supported options: src, width, alt, cname, policy, signature, keys, resolutions
<fs-adaptive src="NxW2v528S9W6K1l5LnFS" width="769px" alt="windsurfer" ></fs-adaptive>
Output:
<picture>
<img src="https://cdn.filestackcontent.com/resize=width:768/NxW2v528S9W6K1l5LnFS"
srcset="https://cdn.filestackcontent.com/resize=width:768/NxW2v528S9W6K1l5LnFS 1x,
https://cdn.filestackcontent.com/resize=width:1536/NxW2v528S9W6K1l5LnFS 2x"
alt="windsurfer"
width="768">
</picture>
Using width descriptors
You can specify generated widths by using resolutions, which takes an array
of numbers or strings (e.g. 540 or '540w').
const options = {
alt: 'windsurfer',
sizes: {
'(min-width: 1080px)': '100vw',
fallback: '90vw',
},
resolutions: [540, 1080],
};
picture(FILESTACK_HANDLE, options);
Output:
<picture>
<source media="(min-width: 1080px)"
sizes="100vw"
srcset="https://cdn.filestackcontent.com/resize=width:540/5aYkEQJSQCmYShsoCnZN 540w,
https://cdn.filestackcontent.com/resize=width:1080/5aYkEQJSQCmYShsoCnZN 1080w">
<img src="https://cdn.f
