Pick

Using our simple yet powerful Javascript API, you can programatically open the Uploader Dialog by calling the pick() function. The dialog will not launch without an API key. To set your key use filepicker.setKey("your_API_KEY");. Filestack's live code examples include an API 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.

Syntax

The javascript pick() 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/v1/filepicker.js"></script>
<script type="text/javascript">
  filepicker.setKey("your_API_KEY");
  filepicker.pick(picker_options, onSuccess(Blob){}, onError(FPError){}, onProgress(FPProgress){});
</script>

Example Pick Code - Open dialog in window mode with cloud drives

Example Code - launch the picker in a new browser window
filepicker.pick( { mimetype: 'image/*', container: 'window', services: ['COMPUTER', 'FACEBOOK', 'INSTAGRAM', 'GOOGLE_DRIVE', 'DROPBOX'] }, function(Blob){ console.log(JSON.stringify(Blob)); }, function(FPError){ console.log(FPError.toString()); });

Parameters

picker_options
An optional dictionary of key-value pairs that specify how the picker behaves.
Container
String
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
String
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
String
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
Integer
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).

Services
String
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
  • COMPUTER
  • DROPBOX
  • EVERNOTE
  • FACEBOOK
  • GMAIL
  • IMAGE_SEARCH
  • FLICKR
  • FTP
  • GITHUB
  • GOOGLE_DRIVE
  • SKYDRIVE
  • PICASA
  • URL
  • WEBCAM
  • INSTAGRAM
  • VIDEO
  • AUDIO
  • ALFRESCO
  • CUSTOMSOURCE (for S3 Source)
  • CLOUDDRIVE
  • IMGUR
  • CLOUDAPP
  • TWITTER

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
String
openTo: 'BOX'

Specifies which service to show upon opening the picker dialog.

Language
String
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.

Mobile UI
Boolean
mobile: true

By default filepicker's v1 library opens the mobile UI on mobile devices. With 'mobile' set to true you can force the dialog box to open in mobile mode on desktops.

Security
Object
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

onSuccess
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

{
    "url":"https://cdn.filestackcontent.com/Knu33RNOQ6qi0S5ND1mY",
    "filename":"calvinhobbes2.jpg",
    "mimetype":"image/jpeg",
    "size":71644,
    "cropped":{
      "originalImageSize":[720,540],
      "cropArea":{"position":[0,0],"size":[720,540]}
    },
    "converted":true,
    "id":1,
    "client":"computer",
    "isWriteable":true
}
onProgress
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

{
    "progress":57.63,
    "filename":"file.jpg",
    "mimetype":"image/jpeg",
    "size":3300503
}
onError
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

{"code":101}