Getting Started
With the Transformations UI, you can allow your users to transform their images with a beautiful, modern interface. This low-code, mobile friendly solution is all built in for you. Your customers will be able to apply filters, adjust image sizes, and perform many other image transformations, providing them with a seamless in-app experience.
We are constantly looking to improve this functionality. Would like to help us?
Open Transformations UI
To integrate Transformations UI with your web application simply include our UMD module in your code:
<script src="https://static.filestackapi.com/transforms-ui/2.x.x/transforms.umd.min.js"></script>
<link rel="stylesheet" href="https://static.filestackapi.com/transforms-ui/2.x.x/transforms.css" />If you want to display result of the image transformations, prepare container for it:
<div style="text-align:center;">
<img id="result" style="width:600px" />
</div>and initialize Transformations UI:
const tr = new FilestackTransform('API_KEY')
tr.open(FILE_URL).then(res => { // replace FILE_URL with the link to the image
document.getElementById('result').src = res // display result of the transformations
})
You can see this code in action below:
Example initialization with CNAME:
const tr = new FilestackTransform('API_KEY', {
client: {
cname: 'fs.yourdomain',
},
});
tr.open(FILE_URL).then(res => { // replace FILE_URL with the link to the image
document.getElementById('result').src = res // display result of the transformations
})
Example initialization with security:
const tr = new FilestackTransform('API_KEY', {
client: {
security: {
policy:'<policy>',
signature:'<signature>'
}
},
});
tr.open(FILE_URL).then(res => { // replace FILE_URL with the link to the image
document.getElementById('result').src = res // display result of the transformations
})
Transform local file
You can ask your user to select file from the file system using standard input and then pass it to the Transformations UI.
<input type="file" id="demoFile"/>
<div style="text-align:center;">
<img id="result" style="width:600px" />
</div>const tr = new FilestackTransform('API_KEY');
// apply listener with Transformations UI on input file change
document.querySelector('#demoFile').addEventListener('change', (res) => {
tr.open(res.target.files[0]).then(res => {
document.getElementById('result').src = res
});
});
You can see this code in action below:
Store transformation
If you would like to store result of the transformations you can easily combine Transformations UI with Filestack JavaScript SDK and it’s upload functionality:
const client = filestack.init('API_KEY'); // initialize Filestack Client with your API key
const tr = new FilestackTransform('API_KEY'); // initialize Transformations UI
tr.setConfigKey('output.blob', true); // set Transformations UI to return blob
tr.open(FILE_URL).then(res => {
client.upload(res).then((uploadRes) => { // upload result of the transformation
document.getElementById('result').innerHTML = JSON.stringify(uploadRes, null, 2);
})
});
You can see this code in action below:
Customization
You can use setConfig or setConfigKey to customize Transformations UI for your needs.
setConfig (dictionary)
Using setConfig you can pass entire configuration object (dictionary) or only part of it. For example:
tr.setConfig({
editor: {
transforms: {
lockRotation: true,
lockFlip: true
}
}
});
setConfigKey (string, AnyType)
Using setConfigKey you can configure specific keys in the config object. For example to achieve exactly same result as with setConfig example above you would use:
tr.setConfigKey('editor.transforms.lockRotation', true)
tr.setConfigKey('editor.transforms.lockFlip', true)
Full config object is available here.
Events
You can interact programmatically with Transformations UI using events. Following methods are available:
| FUNCTION | SIGNATURE | DESCRIPTION |
|---|---|---|
tr.on |
(string, function) | bind to the transform event |
tr.off |
(string, function) | undbind function from the event |
tr.once |
(string, function) | bind only once to the event |
You can use following events:
| EVENT | DESCRIPTION |
|---|---|
layer:text:add |
called on layer text added |
layer:overlay:add |
called on layer overlay added |
image:zoom:change |
called on zoom change |
image:filters:apply |
called after filters apply |
image:crop:start |
called on crop start action |
image:crop:end |
called after image crop |
image:resize |
called when image is resized |
canvas:loading |
called when loading state is changed |
canvas:modified |
called when canvas is modified ie resized, cropped etc |
canvas:save |
called on canvas save |
canvas:undo |
called on undo click |
canvas:clicked |
called canvas element was clicked (excluding layers) |
canvas:selection:changed |
called when filestack layer is selected |
canvas:selection:cleared |
called after selection was cleared |
layer:modified |
called after layer has been modified |
layer:merge |
called after all layers are merged into single image |
layer:add |
called after layer is added |
For example:
const tr = new FilestackTransform('API_KEY');
tr.on('canvas:modified',() => {
console.log("modified!");
});
Config file
Using Config file you can customise the Transformations UI settings.
| CONFIG OPTIONS | CONFIG OPTIONS PARAMS | VALUE | DESCRIPTION |
|---|---|---|---|
| lang | --- | string | add a language to the UI |
| editor | transforms | object | add modifications to the image |
| text | object | add texts to the image | |
| border | object | add borders to the image | |
| filters | object | add filters to the image | |
| adjustments | object | add adjustments to the image | |
| output | format | string | specify the format of the image |
| quality | integer | specify the quality of the image | |
| blob | boolean | export file as blob or url | |
| name | string | output file name |
Below you can find full Transformations UI config file with default settings.
{
lang: 'en',
editor: {
closeOnSave: true, // decide if save should close modal window
topMenu: {
lockRotation: false, // lock top layer menu rotation
lockFlip: false, // lock top flip menu
remove: true, // enable top menu remove button
layers: true, // enable top menu layers management
},
transforms: {
enabled: true, // enable or disable transform module
lockRotation: false,
lockFlip: false,
ratios: [
{
icon: 'crop_free',
default: true,
name: 'Custom',
shape: 'rect',
},
{
icon: `<svg><circle cx="10" cy="10" r="8" stroke="white" stroke-width="2" fill="transparent"/></svg>`,
name: 'Circle',
lockRatio: true, // Controls whether the ratio is user-editable
},
{
icon: 'crop_16_9',
name: '16/9', // The default translation for this ratio
shape: 'rect', // rect, circle
ratio: 16 / 9, // The image aspect ratio (a floating point number) or
lockRatio: true, // Controls whether the ratio is user-editable
},
],
},
text: {
defaults: {
// initial text tool values after creating text
size: 100,
color: '#000000',
backgroundColor: 'transparent',
bold: false,
italic: false,
underline: false,
align: 'left',
initialText: 'Example text.',
},
// font list visible in editor
fonts: [
{
default: true, // set default font for text-tool
displayName: 'Times New Roman',
family: 'Times New Roman, Times, serif',
},
{
displayName: 'Georgia',
family: 'Georgia, serif',
},
{
displayName: 'Palatino Linotype',
family: 'Palatino Linotype, Book Antiqua, Palatino, serif',
},
{
displayName: 'Arial',
family: 'Arial, Helvetica, sans-serif',
},
{
displayName: 'Arial Black',
family: 'Arial Black, Gadget, sans-serif',
},
{
displayName: 'Comic Sans MS',
family: 'Comic Sans MS, cursive, sans-serif',
},
{
displayName: 'Impact',
family: 'Impact, Charcoal, sans-serif',
},
{
displayName: 'Lucida Sans',
family: 'Lucida Sans Unicode, Lucida Grande, sans-serif',
},
{
displayName: 'Tahoma',
family: 'Tahoma, Geneva, sans-serif',
},
{
displayName: 'Trebuchet MS',
family: 'Trebuchet MS, Helvetica, sans-serif',
},
{
displayName: 'Courier New',
family: 'Courier New, Courier, monospace',
},
{
displayName: 'Verdana',
family: 'Verdana, Geneva, sans-serif',
},
{
displayName: 'Lucida Console',
family: 'Lucida Console, Monaco, monospace',
},
{
displayName: 'TLobster',
family: 'Lobster',
cssUrl: 'https://fonts.googleapis.com/css?family=Lobster&display=swap', // we can also load own custom fonts from ie google api or customer defined url
},
],
},
border: {
enabled: true,
defaults: {
width: 25,
opacity: 50,
shadow: false,
color: '#000',
},
},
filters: {
// enabled: true - enable all adjustments or false to disable this module
enabled: [
'blackWhite',
'brownie',
'kodachrome',
'polaroid',
'sepia',
'technicolor',
'vintage',
'iceCold',
'vanillaSky',
'blueOcean',
'autumn',
'milkyWay',
],
// @example
// custom: [
// {
// id: 'milkyWay',
// displayName: 'Milky way',
// matrix: [0, 1.0, 0, 0, 0, 0, 1.0, 0, 0, 0, 0, 0.6, 1.2, 0, 0, 0, 0, 0, 0.9, 0],
// },
// ],
},
adjustments: {
enabled: ['brightness', 'gamma', 'saturation', 'contrast', 'hue', 'noise', 'blur', 'pixelate'],
// enabled: true - enable all adjustments or false to disable this module
},
overlay: {
enabled: true,
defaults: {
opacity: 100,
},
},
},
output: {
format: 'png',
quality: 1,
blob: false, // export file as blob or url
name: null, // output file name if null name will be extracted from url or file element
},
}