Common Picker Recipes

The following are some examples and explanations on how the picker and its many parameters can be used in combination to create a variety of results and behaviors.

Pick with Store Options

The V3 picker has only one pick method and its behavior can be configured with easily readable parameters. The default behavior of V3 is to always store a copy of the selected file. This eliminates the likelihood that your Filestack links will break because the file being selected was moved or deleted from where it existed online. It is still possible to generate symbolic links with V3 and we will demonstrate that on this page in the next example.

Using the storeTo object and its parameters, you can set specific instructions for how your files should be stored. If you don't include any storeTo parameters, then the defaults for your Filestack account will be used.

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

Generate Symbolic Links

Symbolic links can only be generated when selecting files from online sources. In the V3 picker 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.

Generate a 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

The default behavior of the picker is to upload one file at a time since maxFiles defaults to 1 file.

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 still choose to upload less than 3 files.

Pick Max 3 Images
client.pick({ accept: 'image/*', maxFiles: 3, }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })

Force Users to Upload Exactly 3 images.

The V3 picker has a minFiles parameter which prevents users from uploading before they have reached the minimum number of files set. If you set both maxFiles and minFiles, you can guarantee that an exact number of files is uploaded. The minFiles parameter can also ensure that a user uploads at least a certain amount of files. This is not possible in the V2 picker.

Upload Exactly 3 Files
client.pick({ accept: 'image/*', maxFiles: 3, minFiles: 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

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

Setting hideWhenUploading: true along with startUploadingWhenMaxFilesReached: true will hide the picker immediately after a file is selected, because 1 files is the default.

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

Setting hideWhenUploading: true will make it so that the picker will be hidden while the upload happens in the background. The picker will not be hidden until after the user clicks upload. Since uploadInBackground is on by default, to show the true effect of hideWhenUploading, background uploading is disabled in this example.

Hide picker when user clicks upload
client.pick({ hideWhenUploading: true, uploadInBackground: false }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })

Restrict Uploads to Files Smaller Than Given Size.

Use the maxSize parameter to prevent users from uploading files that are too big

Restrict files based on size
client.pick({ maxSize: 2*1024*1024 }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })

Restrict file size and throw custom error if file is too big

The onFileSelected callback allows you to contruct your own logic and even customize your own errors. onFileSelected can be used for much more than just enforcing certain file sizes.

Throw error if selected file is too big
client.pick({ onFileSelected: function(file) { console.log(file.size); if (file.size > 2097152) { throw new Error('Please select a file smaller than ' + 2097152 / 1024 / 1024 + 'MB'); } } }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })

Prevent users from uploading certain types of files

This is not possible in V2. You would need to list out all the mimetypes or extensions you want to allow in order to prevent specific file types from being selected. With onFileSelected you can tell the picker to accept all image types except for PNG.

Set list of file types you don't want
client.pick({ accept: ['image/*'], onFileSelected: function(file) { console.log(file.mimetype); if (file.mimetype = 'image/png') { throw new Error('Please select a file that is not a PNG'); } } }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })

Log Upload Progress

If you combine the upload progress output with the hideWhenUploading parameter, you could build and display your own progress meters for uploads. Progress events fire on every XHR progress event, but these progress events will not fire while background uploads are happening. So you will need uploadInBackground: false in your code as well.

Log Upload Progress
client.pick({ uploadInBackground: false, hideWhenUploading: true, startUploadingWhenMaxFilesReached: true, onFileUploadProgress: function(file, progressEvent) { console.log(JSON.stringify(progressEvent.totalProgressPercent)) } }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })

Set Crop Area Ratio

When the cropping tool loads, if you have set the aspectRatio parameter, you will not be able to expand or contract the crop area beyond the specified ratio. For example, a 16/9 ratio will restrict the crop area to a short, wide rectangle.

Set Crop Ratio
client.pick({ fromSources: ["local_file_system", "dropbox", "googledrive", "onedrive", "box", "facebook", "instagram", "picasa" ], transformations: { crop: { aspectRatio: 16 / 9 } }, }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })

Circle Crop

One of the new transformations available by default in the latest v3 release is circle cropping.

Circle Crop
client.pick({ transformations: { crop: { circle: true } } }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })

Change File Name on Upload

Using onFileSelected you can manipulate the name of the file being uploaded before the upload starts. Currently this only works with files selected from your local device. We are working to add support for cloud sources like instagram and google drive.

Change Filename on Upload
client.pick({ accept: 'image/*', storeTo: { location: 's3' }, onFileSelected: function(file) { file.name = 'foo'; return file; } }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })