Migration to Filestack's V3 Library

Our team of engineers have rebuilt the Filestack Javascript library from the ground up. We also built a brand new Upload API to work in conjunction with the v3 library. While the upgrades from v1 to v2, and v2 Filepicker to v2 Filestack had almost no breaking changes when you switched the library you were pointing to, the tough decision was made with v3 to not follow that trend. This has allowed us to rethink our APIs and hopefully make getting started with Filestack easier by making the function and parameter names more understandable without knowing the intricacies of Filestack.

So, long story short, you will need to refactor your code in order to use v3.

What you need to know about v3

  • The new library is Promise based as opposed to callback driven.
  • filepicker.setKey('your_key') has been replaced by a call to initialize the Filestack client: filestack.init('yourApiKey', { policy: 'policy', signature: 'signature' });. We suggest setting this as a const or var. Security policies and signatures are now passed when the client is initialized instead of being part of the picker options.
  • The number of available methods have been reduced and simplified to make it clearer what each function should do. One of the key examples of this is the pick method. There are no longer three separate methods with slightly different functions. There is one method whose function is to pick (select and upload) files, and the functionality is determined by the parameters included with your options.
  • The parameter names have been altered as well in order to make their function clearer. When you look at picker v3 code, it should read like an English sentence. Given the scenario that you want a user to select up to 3 photos from Facebook, your v3 code might look like this:
      maxFiles: 3,
      accept: 'image/*',
      fromSources: ['facebook'],
    This example could be read like, "pick a max of 3 images from facebook". With v2 , you might have chosen to use pickMultiple with maxFiles, or potentially pickAndStore with the multiple parameter set to true and maxFiles. In v2, you also would have had to choose whether you wanted to use the mimetype(s) or extension(s) parameters. V3's accept parameter will take either and even both at the same time.
  • The default behavior of the picker is now to store the selected files. If you don't have a storage option configured, the files will be stored in Filestack's S3 buckets. Generating symbolic links from files selected from cloud sources is still possible by passing the appropriate parameter.
  • The picker will operate in single file upload mode unless you specify a max or min number of files that should be uploaded.
  • The source from the fromSources parameter are all lowercase now. The same applies to the location names for storeTo.
  • Security policies and signatures are no longer passed as part of the picker options, but rather with your API key when the client is initialized.
  • Due to the manner in which files are uploaded via the new Upload API, if you are using S3, you will need to add some additional CORS configuration rules to your bucket. S3 Cors Configuration
  • Storage options are now passed as part of the picker options via the storeTo parameter.
  • The picker modal shares the same scope as your website and its CSS. If you take a CSS class from the picker and place it in your site's CSS file and tweak the values, it should affect the appearance of the picker.
  • The new library does not currently have an equivalent to the html widgets of v2, it is something that we plan to add. The same goes for the document viewer and responsive image tag widgets. In order to use these, you should stay on v2 for the moment.
  • The v3 picker has a function called onFileSelected which enables a number of custom behaviors to be run based on what is selected. This allows you to script complex behaviors like programmatically changing the name of a file before upload (currently works for local files) or setting a list of file types you don't want the picker to accept.
  • While the v2 store and storeUrl functions could upload files, they performed this action all in one chunk. The new upload method provides the multi-part, direct to S3 functionality of the picker, without the user interface, providing for faster, more reliable uploads.
  • Unlike the convert method from v2, the transform method of the v3 library will take in any URL and return back a Filestack processing engine url. If you need to save the results of that conversion to a new Filestack URL, you can have the new storeUrl method save the converted file.
  • The v3 cropping interface uses Filestack's processing engine to perform image conversions. Each time you make an edit to an image in the interface it will count as a transformation made by your API key. The transformation caching rules still apply though. So for example if you rotate your image 90 degrees, and do this 4 times, that will be like calling the rotate task 4 times, e.g.,
    If you continue to rotate the image in the interface in the same way 100 more times, we will still only count the original 4 rotations as transformations because those are the only times the processing engine url for the image changed, and those settings are already cached.

v2 to v3 Code Comparisons

Here are some simple picker client examples that show what the code might look like when translated from v2 to v3. For more information about the pick method and its parameters consult the v3 pick page.

Store a file to S3

V2 Pick with Store Options
filepicker.pickAndStore( { mimetypes: ["image/*"], }, { location: "S3" }, function(Blob){ console.log(JSON.stringify(Blob)); });
V3 Pick with Store Options
client.pick({ accept: ['image/*'], storeTo: { location: "s3" } }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })

Symbolic links can only be generated when selecting files from online sources. In V3 you have to specify that these are the types of links that you want to generate by using the preferLinkOverStore parameter. If this parameter is set to true and you select a file from your desktop or mobile device, then the file is being stored and is not a symbolic link.

V2 Generate Symbolic Link
filepicker.pick({ services: ['FACEBOOK', 'GOOGLE_DRIVE', 'DROPBOX', 'SKYDRIVE', 'PICASA', 'BOX' ], }, function(Blob) { console.log(JSON.stringify(Blob)); });
V3 Generate Symbolic Link
client.pick({ preferLinkOverStore: true, fromSources: ['facebook', 'googledrive', 'dropbox', 'onedrive', 'picasa', 'box' ], }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })

Upload One Image File

V2 Pick One Image
filepicker.pick( { mimetype: 'image/*' }, function(Blob){ console.log(JSON.stringify(Blob)); });
V3 Pick One Image
client.pick({ accept: 'image/*' }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })

Upload a Maximum of Three Image Files

Have users upload a maximum of 3 Image Files. Users can choose to upload less than 3 files.

V2 Pick Max 3 Images
filepicker.pickMultiple( { mimetype: 'image/*', maxFiles: 3 }, function(Blob){ console.log(JSON.stringify(Blob)); });
V3 Pick Max 3 Images
client.pick({ accept: 'image/*', maxFiles: 3 }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })

Restrict users to uploading JPG or PNG Files

The V3 picker is able to accept a mix of mimetypes and extensions. This is not possible in V2.

V2 Pick a JPG or PNG
filepicker.pick( { extensions: ['.jpg','.png'], }, function(Blob){ console.log(JSON.stringify(Blob)); });
V3 Pick a JPG or PNG
client.pick({ accept: ['image/png','.jpg'], }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })

Hide Picker When Upload Starts

V2 Hide picker and begin upload when max files reached
filepicker.pick( { hide: true, mimetypes: ["image/*"] }, function(Blob){ console.log(JSON.stringify(Blob)); });
V3 Hide picker and begin upload when max files reached
client.pick({ hideWhenUploading: true, startUploadingWhenMaxFilesReached: true, accept: ["image/*"], }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })

Hide Picker When User Clicks Upload

V2 Hide picker when user clicks upload
filepicker.pick( { hide: true, backgroundUpload: false, mimetypes: ["image/*"], services: ["COMPUTER","CONVERT"] }, function(Blob){ console.log(JSON.stringify(Blob)); });
V3 Hide picker when user clicks upload
client.pick({ hideWhenUploading: true, accept: ["image/*"], }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })

Restrict file size and throw error if file is too big

While this functionality is available in both V2 and V3, V3 has an onFileSelected callback that V2 does not. With it you can construct your own logic and even customize your own errors. onFileSelected can be used for much more than just enforcing certain file sizes. For an example of the ways onFileSelected can be used see the v3 examples page.

V2 Throw error if selected file is too big
filepicker.pick( { maxSize: 2097152 }, function(Blob){ console.log(JSON.stringify(Blob)); });
V3 Throw error if selected file is too big
client.pick({ maxSize: 2097152 }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })

Log Upload Progress

V2 Log Upload Progress
filepicker.pick( { mimetype:"image/*", }, function(Blobs){ console.log(JSON.stringify(Blobs)); }, function(error){ console.log(JSON.stringify(error)); }, function(progress){ console.log(JSON.stringify(progress)); } );
V3 Log Upload Progress
client.pick({ uploadInBackground: false, hideWhenUploading: true, startUploadingWhenMaxFilesReached: true, onFileUploadProgress: function(file, progressEvent) { console.log(JSON.stringify(progressEvent.totalPercent)) } }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })

Set Crop Area Ratio and Provide Additional Conversion Options

V2 Set Crop Ratio
filepicker.pick( { cropRatio: 16 / 9, conversions: ['crop', 'rotate', 'filter'] }, function(Blob){ console.log(JSON.stringify(Blob)); });
V3 Set Crop Ratio
client.pick({ transformations: { crop: { aspectRatio: 16 / 9 }, }, }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })

Do Not Allow Image Editing

V2 with no Transform UI
filepicker.pick( { services: ['COMPUTER','FACEBOOK','DROPBOX','INSTAGRAM'] }, function(Blob){ console.log(JSON.stringify(Blob)); });
V3 with no Transform UI
client.pick({ disableTransformer: true, }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })

Change the language used in the picker

V2 using Spanish
filepicker.pick( { language: 'es' }, function(Blob){ console.log(JSON.stringify(Blob)); });
V3 using Spanish
client.pick({ lang: 'es', }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })