filestack-js
Advanced tools
Official web SDK for the Filestack API and content management system.
npm install --save filestack-js
ES module:
import filestack from 'filestack-js';
const apikey = 'abc';
const client = filestack.init(apikey);
Script:
<script src="//static.filestackapi.com/v3/filestack-0.10.1.js"></script>
<script>
const apikey = 'abc';
const client = filestack.init(apikey);
</script>
This library requires an environment that implements the Promise object spec.
If you target IE11 or iOS before 8.0 you will need to add a Promise polyfill to your page or application.
Polyfills we recommend:
Module (for bundling):
Script (for script tag):
object
objectobjectPromisePromisePromisePromisePromisePromisePromisestringPromisestringobjectInitializes the client.
Returns: object - Object containing client methods.
Params
string - Filestack API key. Get a free key here.object - Read about security policies.
string - Filestack security policy encoded in base64.string - HMAC-SHA256 signature for the security policy.string - Custom domain to use for all URLs. This requires the custom CNAME feature on your Filestack app.stringGets current version.
Example
import filestack from 'filestack-js';
console.log(filestack.version);
objectGet current security parameters.
Returns: object - Object containing current security parameters
objectSet security parameters -- useful for changing policy on instantiated client.
Note: Does not currently work with pick. You will need to init a new client if you want to propagate new security parameters to the picker.
Returns: object - Object containing current session parameters
Params
object - Read about security policies.
string - Filestack security policy encoded in base64.string - HMAC-SHA256 signature for the security policy.Example
client.setSecurity({ policy: 'policy', signature: 'signature' });
PromiseLogs out all current cloud sessions.
Returns: Promise - Resolves/rejects when the request succeeds/fails.
PromiseAttaches and opens the picker UI in the current DOM.
Resolve: object - Object contains keys filesUploaded and filesFailed which are both arrays of file metadata objects.
Params
object
Array.<string> - Valid sources are:
local_file_system - Defaulturl - Defaultimagesearch - Defaultfacebook - Defaultinstagram - Defaultgoogledrive - Defaultdropbox - Defaultwebcam - Desktop only. Not currently supported in Safari and IE.video - Desktop only. Not currently supported in Safari and IE.audio - Desktop only. Not currently supported in Safari and IE.evernoteflickrboxgithubgmailpicasaonedriveonedriveforbusinessclouddrivecustomsource - Configure this in your Filestack Dev Portal.string | Array.<string> - Restrict file types that are allowed to be picked. Formats accepted:
.pdf <- any file extensionimage/jpeg <- any mime type commonly known by browsersimage/* <- accept all types of imagesvideo/* <- accept all types of video filesaudio/* <- accept all types of audio filesapplication/* <- accept all types of application filestext/* <- accept all types of text filesstring - Set the default container for your custom source.string - Set the default path for your custom source container.number = 4 - Max number of files to upload concurrently.boolean = false - For cloud sources whether to link or store files.string = "en" - Sets locale. Accepts: da, de, en, es, fr, he, it, ja, ko, nl, no, pl, pt, sv, ru, vi, zh.number = 1 - Minimum number of files required to start uploading.number = 1 - Maximum number of files allowed to upload.number - Restrict selected files to a maximum number of bytes. (e.g. 10 * 1024 * 1024 for 10MB limit).boolean = false - Whether to start uploading automatically when maxFiles is hit.boolean = false - Hide the picker UI once uploading begins.boolean = true - Start uploading immediately on file selection.boolean = false - When true removes the hash prefix on stored files.boolean = false - When true removes ability to edit images.boolean = false - Disables local image thumbnail previews in the summary screen.string = "640x480" - Sets the resolution of recorded video. One of "320x240", "640x480" or "1280x720".object - Specify options for images passed to the crop UI.
boolean | object = true - Enable crop.
number - Maintain aspect ratio for crop selection. (e.g. 16/9, 800/600).boolean - Force all images to be cropped before uploading.boolean = true - Enable circle crop. Disabled if crop.aspectRatio is defined and not 1. Converts to PNG.boolean = true - Enable image rotation.Array.<number> - Specify image dimensions. e.g. [800, 600]. Only for JPEG, PNG, and BMP files.
Local and cropped images will be resized (upscaled or downscaled) to the specified dimensions before uploading.
The original height to width ratio is maintained. To resize all images based on the width, set [width, null], e.g. [800, null].
For the height set [null, height], e.g. [null, 600].Array.<number> - Specify maximum image dimensions. e.g. [800, 600]. Only for JPEG, PNG, and BMP files.
Images bigger than the specified dimensions will be resized to the maximum size while maintaining the original aspect ratio.
The output will not be exactly 800x600 unless the imageMax matches the aspect ratio of the original image.Array.<number> - Specify minimum image dimensions. e.g. [800, 600]. Only for JPEG, PNG, and BMP files.
Images smaller than the specified dimensions will be upscaled to the minimum size while maintaining the original aspect ratio.
The output will not be exactly 800x600 unless the imageMin matches the aspect ratio of the original image.object - Options for local file uploads.
number = 6 * 1024 * 1024 - Size of each uploaded part. This is overridden when intelligent ingestion is enabled.number = 3 - Max number of concurrent parts uploading (chunks of files, not whole files).boolean | string - Enable/disable intelligent ingestion. If truthy then intelligent ingestion must be enabled in your Filestack application. Passing true/false toggles the global intelligent flow (all parts are chunked and committed). Passing 'fallback' will only use FII when network conditions may require it (only failing parts will be chunked).number - Set the default chunk size for intelligent part uploads. Defaults to 8MB on desktop, 1MB on mobile.number = 10 - Number of times to retry a failed part of the flow.number = 2 - Base factor for exponential backoff.number = 120000 - Time in milliseconds to wait before cancelling requests.retryCallback - Called when a retry is initiated.object - Options for file storage.
string - One of s3, gcs, rackspace, azure, dropbox.string - Valid S3 region for the selected S3 bucket. S3 only.stringstringstring - One of public or private.onFileSelected - Called whenever user selects a file.onFileUploadStarted - Called when a file begins uploading.onFileUploadProgress - Called during multi-part upload progress events. Local files only.onFileUploadFinished - Called when a file is done uploading.onFileUploadFailed - Called when uploading a file fails.onUploadStarted - Called when uploading starts (user initiates uploading).function - Called when the UI is exited.function - Called when the UI is mounted.boolean - Reject the returned Promise when a user cancels the pick. The Promise will reject with a list of all files currently selected.boolean = false - Prevent modal close on upload failure and allow users to retry.string = "__filestack-picker" - Id for the root DOM node of the mounted app.boolean - Toggle the drop zone to be active on all views. Default is active only on local file source.boolean - When true the originalFile metadata will be the actual File object instead of a POJO.Array.<number> - Specify [width, height] in pixels of the desktop modal.Example
client.pick({
maxFiles: 20,
uploadInBackground: false,
onOpen: () => console.log('opened!'),
})
.then((res) => {
console.log(res.filesUploaded)
console.log(res.filesFailed)
});
objectThe metadata available on uploaded files returned from pick.
| Name | Type | Description |
|---|---|---|
| filename | string | Name of the file. |
| handle | string | Filestack handle for the uploaded file. |
| mimetype | string | The MIME type of the file. |
| originalPath | string | The origin of the file, e.g. /Folder/file.jpg. |
| size | number | Size in bytes of the uploaded file. |
| source | string | The source from where the file was picked. |
| url | string | The Filestack CDN URL for the uploaded file. |
| originalFile | object | undefined | Properties of the local binary file. |
| status | string | undefined | Indicates Filestack transit status. |
| key | string | undefined | The hash-prefixed cloud storage path. |
| container | string | undefined | The cloud container for the uploaded file. |
| uploadId | string | A uuid for tracking this file in callbacks. |
functionParams
object - File metadata.Example
// Using to veto file selection
// If you throw any error in this function it will reject the file selection.
// The error message will be displayed to the user as an alert.
onFileSelected(file) {
if (file.size > 1000 * 1000) {
throw new Error('File too big, select something smaller than 1MB');
}
}
// Using to change selected file name
// NOTE: This currently only works for local uploads
onFileSelected(file) {
file.name = 'foo';
// It's important to return altered file by the end of this function.
return file;
}
functionParams
array - All currently selected files.functionParams
object - File metadata.functionParams
object - File metadata.functionParams
object - File metadata.error - Error instance for this upload.functionParams
object - File metadata.object - Progress event.
number - Percent of file uploaded.number - Total number of bytes uploaded for this file.Appends a drop zone into the DOM node specified by paneOptions.id. This feature is powered by the picker and supports the validation and callback options through pickOptions.
Params
object
string - Required: Id for the DOM node that will mount the drop pane.boolean = true - Toggle the full-page drop zone overlay.function - Callback for dragenter events.function - Callback for dragleave events.function - Callback for dragover events.function - Callback for drop events.function - Callback that is passed a list of uploaded file metadata.function - Callback that is passed a list of failed file metadata.function - Callback that is passed a number representing total progress percent for all dropped files.function - Callback for drop pane click event.boolean - Disable file input on click.boolean = true - Toggle icon element in drop pane.boolean = true - Toggle upload progress display.string - Customize the text content in the drop pane.boolean - Toggle the crop UI for dropped files.client.pick. fromSources is ignored.Example
<div id="dropzone" style="width:500px;height:300px;"></div>
client.makeDropPane({
id: 'dropzone',
onSuccess: res => console.log(res),
}, {
maxFiles: 2,
});
Promise ⏏Opens the crop UI for the specified list of files or URLs.
Resolve: object - Object contains keys filesUploaded and filesFailed which are both arrays of file metadata.
Params
array - An array of URL or File/Blob values to transform.client.pick. fromSources is ignored.Example
<input id="fileSelect" type="file">
const inputEl = document.getElementById('fileSelect');
const pickOptions = { transformations: { crop: true, circle: false } };
inputEl.addEventListener('change', (e) => {
client.cropFiles(e.target.files, pickOptions)
.then(res => console.log(res));
});
// Or pass an array of URL strings
const urls = [
'https://d1wtqaffaaj63z.cloudfront.net/images/fox_in_forest1.jpg',
'https://d1wtqaffaaj63z.cloudfront.net/images/sail.jpg',
];
client.cropFiles(urls).then(res => console.log(res));
PromiseInterface to the Filestack Store API. Used for storing from a URL.
Resolve: object - Metadata of stored file.
Reject: error - A Superagent error object.
Params
string - Valid URL to a file.object
stringstring = "s3" - One of s3, gcs, rackspace, azure, dropbox.stringstringstringstring - Valid S3 region for the selected container (S3 only).string - One of public or private.Example
client
.storeURL('https://d1wtqaffaaj63z.cloudfront.net/images/NY_199_E_of_Hammertown_2014.jpg')
.then(res => console.log(res));
PromiseInterface to the Filestack Retrieve API. Used for accessing files via Filestack handles.
Resolve: object - Metadata of stored file, depending on metadata / head option.
Reject: error - A Superagent error object.
Params
string - Valid Filestack handle.object
boolean - return json of file metadataboolean - perform a 'head' request instead of a 'get'boolean - X-File-Name will be returnedstring - add extension to handleExample
client
.retrieve('DCL5K46FS3OIxb5iuKby')
.then((blob) => {
const urlCreator = window.URL || window.webkitURL;
const imageUrl = urlCreator.createObjectURL(blob);
document.querySelector('#myImage').src = imageUrl;
})
.catch((err) => {
console.log(err);
}));
PromiseInterface to the Filestack Remove API. Used for removing files, requires security to be enabled.
Resolve: object - Result of remove.
Reject: error - A Superagent error object.
Params
string - Valid Filestack handle.Example
client
.remove('DCL5K46FS3OIxb5iuKby')
.then((res) => {
console.log(res);
})
.catch((err) => {
console.log(err);
}));
PromiseInterface to the Filestack Metadata API. Used for retrieving detailed data of stored files.
Resolve: object - Result of metadata.
Reject: error - A Superagent error object.
Params
string - Valid Filestack handle.object
booleanbooleanbooleanbooleanbooleanbooleanbooleanbooleanbooleanbooleanbooleanbooleanbooleanbooleanbooleanbooleanbooleanbooleanbooleanExample
client
.metadata('DCL5K46FS3OIxb5iuKby')
.then((res) => {
console.log(res);
})
.catch((err) => {
console.log(err);
}));
Used for viewing files via Filestack handles, requires Document Viewer addon to account. Opens document viewer in new window if ID option is not provided.
Params
string - Valid Filestack handle.object
string - Id for iframe container element.string - Filestack security policy (overrides client session).string - Filestack security signature (overrides client session).string - URL to custom CSS.Example
client.preview('KW9EJhYtS6y48Whm2S6D', { id: 'previewId', css: 'https://www.linktoyourcss.com'});
stringInterface to the Filestack transformation engine.
Returns: string - A new URL that points to the transformed resource.
Params
string - Valid URL to an image.transformOptions - Transformations are applied in the order specified by this object.Example
const transformedUrl = client.transform(url, {
crop: {
dim: {
x: 0,
y: 50,
width: 300,
height: 300,
},
},
vignette: {
blurmode: 'gaussian',
amount: 50,
},
flip: true,
};
// optionally store the new URL
client.storeURL(transformedUrl).then(res => console.log(res));
objectParams
object - Crop options.
object - Crop dimensions.
numbernumbernumbernumberobject - Resize options. At least one option is required.
numbernumberstring - One of clip, crop, scale, max.string - One of center, top, bottom, left, right, faces, or align pair like ['top', 'left'].object - Rotate options. At least one option is required.
number | string - Can be number in range 0-359 or exif.booleanstringboolean - Flip imageboolean - Flop imageobject - Rounded corners options.
number | string - Can be number in range 1-10000 or max.numberstringobject - Vignette options.
numberstring - One of linear or gaussian.stringobject - Polaroid options.
stringnumberstringobject - Torn edges options.
Array.<number> - Range format [10, 50].stringobject - Shadow options.
numbernumberArray.<number> - Range format [25, 25].stringstringobject - Circle options.
stringobject - Border options.
numbernumbernumberboolean - Monochrome.object - Sepia.
numberobject - Output options.
stringstringArray.<number> - Range format [1, 10000].Array.<number> - Range format [1, 500].booleannumber | string - Can be number in range 1-100 or input.booleanbooleanstring - One of rgb, cmyk, or input.booleanbooleanstring - One of a3, a4, a5, b4, b5, letter, legal, or tabloid.string - One of landscape or portrait.PromiseInitiates a direct-to-S3 multi-part upload. Uses Filestack S3 by default. Read how to configure your own S3 buckets here.
Resolve: object - Metadata of uploaded file.
Reject: error - An Error object depending on where the flow halted.
Params
Blob | string - must be a valid File, Blob, or base64 encoded string.object
number = 6 * 1024 * 1024 - Size of each uploaded part. This is hardcoded to 8MB when intelligent ingestion is enabled. To control chunk sizes please use intelligentChunkSize.number = 3 - Max number of concurrent parts uploading.boolean | string - Enable/disable intelligent ingestion. If truthy then intelligent ingestion must be enabled in your Filestack application. Passing true/false toggles the global intelligent flow (all parts are chunked and committed). Passing 'fallback' will only use FII when network conditions may require it (only failing parts will be chunked).number - Set the default chunk size for intelligent part uploads. Defaults to 8MB on desktop, 1MB on mobile.number = 10 - Number of times to retry a failed part of the flow.number = 2 - Base factor for exponential backoff.number = 10000 - Upper bound in milliseconds for retry wait time.number = 120000 - Time in milliseconds to wait before cancelling requests.number = 1000 - Frequency (in milliseconds) at which progress events are dispatched.progressCallback - Called regularly to give progress updates.retryCallback - Called when a retry is initiated.object - Configure where the file is stored.
string - Define a custom filename for the Blob/File being uploaded.string = "s3" - Valid options are: s3, gcs, dropbox, azure, rackspace.string - Valid S3 region for the selected container (S3 only).string - Name of the storage container.string - Path where the file will be stored. A trailing slash will put the file in that folder path.string - Valid options are private or public.object - A control token that can be used to call cancel(), pause(), and resume().Example
const token = {};
const onRetry = (obj) => {
console.log(`Retrying ${obj.location} for ${obj.filename}. Attempt ${obj.attempt} of 10.`);
};
client.upload(file, { onRetry }, { filename: 'foobar.jpg' }, token)
.then(res => console.log(res));
token.pause(); // Pause flow
token.resume(); // Resume flow
token.cancel(); // Cancel flow (rejects)
functionParams
object - Progress event.
number - Percent of total file upload progress.number - Total number of bytes uploaded thus far across all parts.functionParams
object - Retry information object.
string - Which part of the flow is being retried.Array.<object> - Array of current parts at this point in the flow.string - Name of the file being retried.number - Current attempt.© 2017 Filestack.
0.10.1 (2017-12-14)
Picker changes
uploadConfig.timeout not being respectedFAQs
Official JavaScript library for Filestack
The npm package filestack-js receives a total of 72,053 weekly downloads. As such, filestack-js popularity was classified as popular.
We found that filestack-js demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.