Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/filestack/adaptive
Generate responsive HTML picture elements powered by on-the-fly Filestack image conversions.
https://github.com/filestack/adaptive
adaptive filestack html5 html5-picture image-resizing images jsx picture react responsive webp
Last synced: 2 months ago
JSON representation
Generate responsive HTML picture elements powered by on-the-fly Filestack image conversions.
- Host: GitHub
- URL: https://github.com/filestack/adaptive
- Owner: filestack
- License: mit
- Created: 2017-11-01T18:30:22.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2023-01-03T18:06:13.000Z (about 2 years ago)
- Last Synced: 2024-03-25T21:52:59.547Z (10 months ago)
- Topics: adaptive, filestack, html5, html5-picture, image-resizing, images, jsx, picture, react, responsive, webp
- Language: TypeScript
- Homepage: https://filestack.github.io/adaptive/
- Size: 2.13 MB
- Stars: 31
- Watchers: 14
- Forks: 3
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
Generate responsive HTML picture elements powered by on-the-fly Filestack image conversions.
**Table of Contents**
- [What is Adaptive](#what-is-adaptive)
- [Features](#features)
- [Usage](#usage)
- [Browser](#browser)
- [SRI](#sri)
- [Node (react example)](#node-react-example)
- [Use with JSX](#use-with-jsx)
- [Storage aliases and external urls](#storage-aliases-and-external-urls)
- [Image width and pixel density](#image-width-and-pixel-density)
- [Webcomponent](#webcomponent)
- [Using width descriptors](#using-width-descriptors)
- [WebP support](#webp-support)
- [Custom CNAME](#custom-cname)
- [Transformations support](#transformations-support)
- [Disable validator](#disable-validator)
- [Development](#development)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [Future](#future)
## What is Adaptive
Adaptive is a tool which allow [Filestack](https://github.com/filestack/filestack-js) 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](https://www.filestack.com/docs/concepts/getting-started/#vocabulary), [storage aliases](https://www.filestack.com/docs/concepts/storage/#storage-aliases) and external urls
- Support for different sizes and formats in srcSet
- Allows you to add some [image transformations](https://www.filestack.com/docs/api/processing/#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
```html
const options = {
alt: 'windsurfer',
sizes: {
fallback: '60vw',
}
};
const el = fsAdaptive.picture(FILESTACK_HANDLE, options);
document.body.appendChild(el);
```
Output:
```html
```
#### 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
```
```HTML
```
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)
```bash
npm install filestack-adaptive
```
```js
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 `` element you can call **makePictureTree** directly in your JSX
```js
import React, { Component } from 'react';
import { makePictureTree } from 'filestack-adaptive';
class Picture extends Component {
renderSources(sources) {
return sources.map((sourceObj) => {
return ;
});
}
renderImage(imageObj) {
return ![]()
;
}
render() {
const tree = makePictureTree(this.props.handle, this.props);
return (
{tree.sources && this.renderSources(tree.sources)}
{this.renderImage(tree.img)}
);
}
}
export default Picture;
```
### Storage aliases and external urls
You can also use [Filestack storage alias](https://www.filestack.com/docs/concepts/storage/#storage-aliases) or external urls as an image source:
```html
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);
```
### 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']`.
```js
const options = {
alt: 'windsurfer',
width: '768px',
};
picture(FILESTACK_HANDLE, options);
```
Output:
```html
```
### Webcomponent
Adaptive now supports webcomponent. Supported options: src, width, alt, cname, policy, signature, keys, resolutions
```HTML
```
Output:
```html
```
### Using width descriptors
You can specify generated widths by using `resolutions`, which takes an array
of numbers or strings (e.g. `540` or `'540w'`).
```js
const options = {
alt: 'windsurfer',
sizes: {
'(min-width: 1080px)': '100vw',
fallback: '90vw',
},
resolutions: [540, 1080],
};
picture(FILESTACK_HANDLE, options);
```
Output:
```html
```
### WebP support
WebP can be used when it's supported by the browser. Filestack will take care of the image conversion
and cache it on the delivery network for future requests.
```js
const options = {
alt: 'windsurfer',
formats: ['webp', 'jpg'], // order matters!
};
picture(FILESTACK_HANDLE, options);
```
Output:
```html
```
### Custom CNAME
In order to use custom cname for generated file links just use cname option:
```js
const options = {
cname: 'fs.test123.com'
};
picture(FILESTACK_HANDLE, options);
```
Output:
```html
```
### Transformations support
Adaptive also supports Filestack transformations.
Available options are listed in doc:
https://www.filestack.com/docs/image-transformations
```js
const options = {
alt: 'windsurfer',
width: 400,
transforms: {
blur: {
amount: 5
},
border: true, // use default options of border transformation
}
};
picture(FILESTACK_HANDLE, options);
```
Output:
```html
```
#### Disable validator
To speed up generating of final output (useful when you have a bunch of images on your site) you can optionally disable validation of transformation params by passing additional prop in options:
```js
const options = {
...
useValidator: false,
...
}
```
## Development
To install and work on Adaptiv locally:
```bash
git clone [email protected]:filestack/adaptive.git
cd adaptive
npm install
```
To create build directory:
```
npm run build
```
This newly created directory contains
```text
build/
├── browser/ # for the UMD module (usable in HTML script tags)
└── index.umd.js #
├── main/ # for the CommonJS module
├── ... #
└── index.js #
└── module/ # for the ES Module (suitable for bundlers like Webpack and Rollup)
├── ... #
└── index.js #
```
## Documentation
For more info about available methods and options check browser documentation:
https://filestack.github.io/adaptive/
## Contributing
We follow the [conventional commits](https://conventionalcommits.org/) specification to ensure consistent commit messages and changelog formatting.
## Future
Adaptive is joining an ecosystem already populated with many utilities for responsive images.
We want to remain flexible while still having some opinions on how to implement picture elements using Filestack conversions, and we know it is hard to
cover every use case. Contributions and ideas are welcome that would help improve the usefulness of this library.
Current ideas:
* LQIP using the Filestack blur transformation
* Compress HiDPI images using Filestack compress task
* Implement art direction with Filestack crop
* Develop a PostHTML transform for post-processing HTML using `makePictureTree`