Getting Started

Filestack Architecture

File Upload

File Export (Save To)

Responsive Images

Image Transformations

Document Transformations

Video Transcoding

Audio Transcoding





Filestack Viewer


Supported Cloud Drives

Filestack Recipes

Filestack Integrations

Filestack SDKs

Register for an API key

Pick - Upload a File From Anywhere

So you have an upload form, but you're ready to supercharge it by connecting it to everything from Dropbox to webcams - you've come to the right place. Using the javascript api for picking files, you simply ask for a file and get a url back, which you can pass to upload to your server or even use locally. Here's how it works:

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 or set your key for you if you visit this page directly from the developer portal.

Basic example
filepicker.pick( function(Blob){ console.log(replaceHtmlChars(JSON.stringify(Blob))); } );
Only images
filepicker.pick( { mimetype: 'image/*', container: 'window', services: ['COMPUTER', 'FACEBOOK', 'CLOUDAPP'] }, function(Blob){ console.log(replaceHtmlChars(JSON.stringify(Blob))); }, function(FPError){ // console.log(FPError.toString()); - print errors to console } );
Important - if you want all files to be uploaded directly to your own storage rather than remaining a reference, you should use the filepicker.pickAndStore function. Using the .pick() function will return a symlink, meaning if the user deletes the underlying file from Dropbox, Facebook, etc. your link will return a 404 - File not found. On the other hand, the symlink means that you can poll the url to check for changes, so which is best depends on your app's needs.


filepicker.pick(picker_options, onSuccess(Blob){}, onError(FPError){}, onProgress(FPProgress){})

An optional dictionary of key-value pairs that specify how the picker behaves:


{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).


{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.


{language: 'es'}

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

Currently, 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.


{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 Choose Plan

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 Location

{openTo: 'BOX'}

Specifies which service to show upon opening.

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 Source Client container

{customSourceContainer: 'mybucket'}

Specify a bucket name to be used for your Custom Source (S3) client

Custom Source Client path

{customSourcePath: 'some_folder/another_folder'}

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

Debug mode

{debug: true}

Useful when developing, makes it so the onSuccess callback is fired immediately with dummy data.


{policy: POLICY, signature: SIGNATURE}

If you have security enabled, you'll need to have a valid 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

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 css

{customCss: '//'}

Allow to set custom css file url per dialog instance. You can set this option also in developer portal for all application integrations. Since dialog v2 was completely rebuilt from the ground up, custom css files from v1 will not work correctly with it. For more information about using custom css with v2 click here. CustomCss is only available on paid Filestack plans.

Custom CSS is only available on the STARTER and higher plans. Choose Plan

Custom Dialog Text

{customText: '//'}

Allows a user to provide their own text for the Filestack dialog. Url should use https protocol. 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}}.

Client side image compression and resize

Note: client side compression and resizing relies on the dialog being opened to work. If a user utilizes the drop-pane functionality (meaning no modal dialog window opens) to upload their images, their images will not be modified.

Client side image compression and resizing concerns local & webcam images and is available for mobile and desktop devices. 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 max size.

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.

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.


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 core 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.
Note: the "key" parameter is deprecated and will be removed soon. If you want to store files immediately after picking, use the filepicker.pickAndStore call.

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

For more info about FPErrors, see Error Handling.


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