Pick and Store

While the pickMultiple() method allows the user to upload more than one file at once. If these files are being selected from cloud sources like Facebook, the links generated will be symlinks. The pickAndStore() method will make a copy of each file and store it either in Filestack's storage or cloud storage option you have configured for your account.

Please Note: The picker will not launch without an API key. To set your key use filepicker.setKey("your_API_KEY"). Filestack's documentation examples includes a key in the background, but if you want to test something using your own key, you can always add filepicker.setKey("YOUR_API_KEY") to the live code examples.


The javascript pickAndStore() function can be called anytime after the apikey has been set in order to display the Picker dialog. You may pass in an optional dictionary of key-value pairs to customize the options of the Upload dialog. Handler functions are also optional, and can be passed in as callback functions for the events onProgress, onSuccess, and onError.

<script src="https://api.filepicker.io/v2/filepicker.js"></script>
<script type="text/javascript">
  filepicker.pickAndStore(picker_options, store_options, onSuccess(Blob){}, onError(FPError){}, onProgress(FPProgress){});

Example Pick And Store Code

Example Code - pickAndStore in multiple mode with upload progress console output
filepicker.pickAndStore( { mimetype:"image/*", multiple: true }, { location:"S3" }, function(Blobs){ console.log(JSON.stringify(Blobs)); }, function(error){ // console.log(JSON.stringify(error)); - print errors to console }, function(progress){ console.log(JSON.stringify(progress)); } );


An optional dictionary of key-value pairs that specify how the picker behaves.
container: 'modal'

Where to load the Filestack UI into. Possible values are "window", "modal", or the id of an iframe in the current document. Defaults to "modal" for desktop browsers and 'window' for mobile browsers.

mimetype: 'image/*'
mimetypes: ['image/*', 'text/*',…]

Specify the type of file that the user is allowed to pick. For example, if you only want the user to select images, you could specify image/* and users would only be able to select images to upload. Similarly, you could specify application/msword to only allow Word Documents to be selected.

You can also specify an array of mimetypes to allow the user to select a file from any of the given types.

extension: '.pdf'
extensions: ['.js', '.coffee',...]

Specify the type of file that the user is allowed to pick by extension. Do not use this option with mimetype(s) specified as well.

You can also specify an array of extensions to allow the user to select a file from any of the given types.

Max Size
maxSize: 1024*1024

Limit uploads to be at most maxSize, specified in bytes. By default file size is not limited. For example, to make sure files are all less than 10MB, use "10485760" (10*1024*1024).

multiple: true

Specify that the user can upload multiple files, akin to pickMultiple.

Max Files
maxFiles: 5

Specify the maximum number of files that the user can upload at a time. If the user tries to upload more files than this limit, they will be presented with an error message. By default, there is no cap on the number of files a user can upload.

folders: true

Indicate that users should be able to drop entires folders worth of files at a time. Due to browser support, this is currently only available in recent versions of Chrome. This parameter only applies when multiple is set to be true. By default, folders are not allowed (false).

service: 'FACEBOOK'
services: ['FACEBOOK','BOX',…]

Specify which services are displayed on the left panel, and in which order, by name.

Be sure that the services you select are compatible with the mimetype(s) or extension(s) specified.

Currently, Filestack supports the following services, and we're adding more all the time:

  • BOX
  • FTP
  • URL
  • CUSTOMSOURCE (for S3 Source)

S3 Source is a premium feature available only on PREMIUM and PRO plans. More info

For all new applications, it is required to set your own Dropbox OAuth keys in order to use the Dropbox service with Filestack. More info

The COMPUTER service should be specified if you want users to be able to select files from their local device (their desktop or mobile device). To learn more about local file uploads Click Here

Default Service
openTo: 'BOX'

Specifies which service to show upon opening the picker dialog.

language: 'es'

Specify the filestack dialog language version. If not set, it will use language detected in the browser. If the detected language is unavaliable, the default value is 'en'.

Supported languages:

  • Czech: 'cs'
  • German: 'de'
  • English: 'en'
  • Spanish: 'es'
  • Spanish (Mexican): 'es_mx'
  • Faroese: 'fo'
  • French: 'fr'
  • Canadian French: 'fr_ca'
  • Hebrew: 'he'
  • Italian: 'it'
  • Dutch: 'nl'
  • Danish: 'da'
  • Norwegian: 'no'
  • Polish: 'pl'
  • Portuguese: 'pt'
  • Portuguese (Brazilian): 'pt_br'
  • Russian: 'ru'
  • Swedish: 'sv'
  • Turkish: 'tr'
  • Chinese (Taiwan): 'zh_tw'
  • Greek: 'el'
  • Spanish (Argentina): 'es_ar'
  • Finnish: 'fi'
  • Indonesian: 'id'
  • Korean: 'ko'
  • Slovak: 'sk'
  • Ukrainian: 'uk'
  • Chinese: 'zh'
  • Serbian: 'sr'
  • Bulgarian: 'bg'
  • Malay: 'ms'
  • Hungarian: 'hu'
  • Vietnamese: 'vi'

If you would like to co-create the translation to any language, please contact us.

Background upload
backgroundUpload: true

Background uploads are available in multiple mode. Uploads will start immediately after the user selects a file. By default this is set to true.

Hide modal
hide: true

Hides the modal immediately after file is selected. The upload will continue in the background and progress callbacks will continue to be fired as the upload happens. By default this is set to false. Works only for modal mode.

Custom Source Client container
customSourceContainer: 'mybucket'

Specify the name of the bucket to be used for your CustomSource (S3) client

Custom Source Client path
customSourcePath: 'some_folder/another_folder'

Define the default folder which will be used as the root path in the CustomSource Client

WebCam Output Resolution
webcamDim: [1280, 720]

Set the resolution of the images that the Filestack webcam outputs. Image size is limited by the resolution of user's webcam. If used alone, webcamDim does not need to be part of the webcam: {} object required by videoRes.

WebCam Video Output Resolution
webcam: {videoRes: "1280x720"}

Set the resolution of the video that the Filestack webcam outputs from the VIDEO service. There are three possible settings, "320x240", "640x480" and "1280x720". If not set the default is "640x480". videoRes needs to be included in a webcam: {} object. If used in conjunction with webcamDim, then both should be included in the webcam object like this: webcam: {videoRes: "1280x720", webcamDim: [1280, 720]}.

Set length of Audio Recording
webcam: {audioLen: "120"}

Set a limit to how long the audio recordings generated by the AUDIO service can be. Values are in seconds. The default is 3600 (60 minutes), the maximum possible value is 5400 (90 minutes). This parameter must be part of a webcam: {} object like webcam: {videoLen: 120, audioLen: 120}.

Set length of Video Recording
webcam: {videoLen: "120"}

Set a limit to how long the Video recordings generated by the VIDEO service can be. Values are in seconds. The default is 3600 (60 minutes), the maximum possible value is 5400 (90 minutes). This parameter must be part of a webcam: {} object like webcam: {videoLen: 120, audioLen: 120}.

Custom CSS
customCss: '//domain.com/link_to_your_css.css'

Use a custom CSS file to customize the appearance of each dialog instance. You can also set this option globally in the developer portal so the same CSS is used for all dialog instances. The URL of your CSS file should use the https protocol and be publicly accessible. To learn more about customizing the upload dialog click here. The customCss parameter and global setting are only available on paid Filestack plans.

Custom Dialog Text
customText: '//domain.com/your_json_file.json'

Allows a user to provide their own text for the Filestack dialog. The URL of your JSON file should use https protocol and be publicly accessible. Here is a sample JSON file including the English text for the dialog that can be used as a base for your custom text: English_Dialog_Text.JSON Your custom text must include all the keys present in this file. The values can be blank if you choose. Other language files are available by using the language code to modify the url linking to this French translation file, so es.js for Spanish, ru.js for Russian, pl.js for Polish, etc. The sample French file above contains variables that look like this: __variable__, however in order to work with the customText picker option, these variables must adhere to this format: {{variable}}.

policy: POLICY, signature: SIGNATURE

If you have security enabled, you will need to include a valid Filestack policy and signature in order to perform the requested call. This allows you to select who can and cannot perform certain actions on your site. Read more about security and how to generate policies and signatures

Client side image compression and resize


Client side image compression and resizing concerns local & webcam images and is available for mobile and desktop devices. These functions also rely on the dialog being open to work. If a user utilizes the drop-pane functionality to upload their images, meaning no modal dialog window opens, their images will not be modified.

See more
Image quality
imageQuality: 80

Specify the image quality/compression ratio. Range 0 - 100. 100% quality = 0 compression. By default there is no compression. Works only for jpeg images.

Image dimensions
imageDim: [width, height]

Specify image dimenions. e.g. : {imageDim: [800, 600]}. Local 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], eg. [800, null]. For the height set [null, height], eg [null, 600].

Max image dimensions
imageMax: [width, height]

Specify maximum image dimenions. e.g. : {imageMax: [800, 600]}. 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.

Min image dimensions
imageMin: [width, height]

Specify minimum image dimenions. e.g. : {imageMin: [800, 600]}. 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.

Crop UI


To include the crop UI in a widget add the 'CONVERT' service to the services list. 'CONVERT' is included by default.

See more
conversions: ['crop', 'rotate', 'filter']

When used in conjunction with the 'CONVERT' service, the conversions array allows you to specify what functions are available in the UI for the user. Include 'crop' to allow the user to crop an image, include 'rotate' to allow a user to rotate the uploaded image left or right, include filter to allow user to blur or sharpen the uploaded image. You can include all the services or a selection of the three. If 'CONVERT' is specified, but no conversions are set, the default behavior is to display the cropping tool only.

Crop ratio
cropRatio: 4/3

Specify the crop area height to width ratio. This can be a float, an integer or a ratio like 4/3 or 16/9. By default it is not specifed.

Crop area dimensions
cropDim: [width, height]

Specify a crop area with fixed dimenions. e.g. : {cropDim: [800, 600]}. The user will only be allowed to move the crop area. If the image is smaller than the specified dimensions the crop area will fill the image.

Max crop dimensions
cropMax: [width, height]

Specify the maximum dimensions of the crop area. e.g. : {cropMax: [800, 600]}. If the image is smaller than the specified dimensions it won't be applied. Can be used in conjunction with cropRatio and cropMin.

Min crop dimensions
cropMin: [width, height]

Specify crop area minimum dimensions. e.g. : {cropMin: [400, 300]}. Can be used together with cropMax and cropRatio

Force to crop
cropForce: true

If set to true, the user will have to crop all images before uploading them. This works for both single and multiple files mode but no if 'hide' option is set to true. By default set to false.

An required dictionary of key-value pairs that specify how the picker behaves.
location: 'S3'

Where to store the file. The default is S3. Other options are 'azure', 'dropbox', 'rackspace' and 'gcs'. You must have configured your storage in the developer portal to enable this feature. Note: Rackspace, Azure, Dropbox and Google Cloud are only available on the PLUS and higher plans.

path: '/myfiles/1234.png'

The path to store the file at within the specified file store. For S3, this is the key where the file will be stored at. By default, Filestack stores the file at the root at a unique id, followed by an underscore, followed by the filename, for example "3AB239102DB_myphoto.png".

If the provided path ends in a '/', it will be treated as a folder, so if the provided path is "myfiles/" and the uploaded file is named "myphoto.png", the file will be stored at "myfiles/909DFAC9CB12_myphoto.png", for example.

If the multiple option is set to true, only paths that end in '/' are allowed.

Store Container
storeContainer: 'user-photos'

The bucket or container in the specified file store where the file should end up. This is especially useful if you have different containers for testing and production and you want to use them both on the same Filestack app. If this parameter is omitted, the file is stored in the default container specified in your developer portal.

Note: This parameter does not apply to the Dropbox file store.

Store Region
storeRegion: 'us-east-1'

The region where your storage container is located. This setting currently applies only to S3 buckets. If you are using a different bucket and region than the one you set up in your developer portal you can pass the storeRegion as part of your store options. If this parameter is not set we will do our best to determine the region your S3 bucket is located so that we can properly authenticate our connection request. You can find a list of the S3 regions here: in the "region" column.

Public Access
access: 'public'

Indicates that the file should be stored in a way that allows public access going directly to the underlying file store. For instance, if the file is stored on S3, this will allow the S3 url to be used directly. This has no impact on the ability of users to read from the Filestack file URL. Defaults to 'private'.

The function to call if a file is picked successfully.

We'll return a Blob as a JSON object with the following properties.

url The main Filestack file url on which all other operations are based.
filename The filename of the uploaded file.
mimetype The mimetype of the uploaded file.
size The size of the uploaded file in bytes, if available.
isWriteable Whether the file can be written to using filepicker.write.

Sample response

The function that is called on uploading progress events. The function will show the percent completed as a number out of 100. Multiple mode provides separate callbacks for all selected files.

We'll retrun a JSON object with the following properties:

progress Current progress as a float number.
filename The filename of the file being uploaded.
mimetype The mimetype of the file being uploaded.
size The size of the file being uploaded in bytes if available.

Sample response

The function to call if there is an error when picking a file.

Possible error codes on the FPError:

101 The user closed the dialog without picking a file
400 Bad parameters were passed to the server. This often will be the case when you turned on security but haven't passed up a policy or signature.
403 Invalid request - The policy and/or signature don't allow you to make this request. For more information see Security Documentation.

For more info about FPErrors, see Error Handling.

Sample response