JavaScript File Picker

Getting Started

To start with Web File Picker you will need Filestack application and API key. Please read our Quick Start guide that explains basic vocabulary and features available at Filestack. File Picker is part of our open source JavaScript SDK.

Opening File Picker

To integrate Filestack File Picker with your web application simply include our JavaScript SDK UMD module in your code:

<script src="//"></script>

Read about other ways of including our JavaScript SDK from our JavaScript SDK Reference.

Once Filestack code is included you can configure client with your API Key. Code below is all that is required to open default File Picker.

const client = filestack.init(YOUR_API_KEY);

Picker Response

For each uploaded file, PickerFileMetadata object is created with file details, unique handle and CDN URL. This object can be accessed using callbacks when upload is finished.

PickerFileMetadata interface
  "filename": "myfile.png",
  "handle": "AFrHW1QRsWxmu5ZLU2qg",
  "mimetype": "image/png",
  "originalPath": "picker_transformation.png",
  "size": 1277297,
  "source": "local_file_system",
  "url": "",
  "uploadId": "cfcc198e63b7328c17f09f1af519fcdf",
  "originalFile": {
    "name": "myfile",
    "type": "image/png",
    "size": 1277297
  "status": "Stored"
handle string Filestack’s unique identifier of the uploaded file.
url string Unique CDN url to access uploaded file.
filename string Name of the uploaded file. This can be changed in the PickerOptions.
mimetype string Mimetype of the uploaded file.
size int Size of the uploaded file.
source string Source of the uploaded file.
status string Status of the upload. Can be either Stored or InTransit for CIN and FII.
originalFile Object Object representing original file, its name, type and size.
originalPath string Original path from where the file was uploaded.
uploadID string Uniqe id of the upload for debugging.
PickerResponse interface

When using onUploadDone callback you will receive PickerResponse that represents state of all the files that were uploaded during given Picker session. Both filesUploaded and filesFailed are arrays of PickerFileMetadata objects explained above. For example:



Picker Options

While default File Picker implementation is suitable for basic use cases, you can easily configure your instance in multiple ways. To do that you can use PickerOptions interface.

Most used options are:

  • Picker Options - master set of options you can use to specify default File Picker behavior and limitations.
  • Store Options - control where and how files should be stored.
  • Upload Options - control how your files are uploaded to your storage destination.
  • Transformation Options - control how your users transform files before they are stored.

We will present most important options below but full specification can be found in our JavaScript SDK Reference.

fromSources array

Using fromSources array you can configure list of services you would like to display to your users so they can choose files from. Example below limits sources to local computer, Intagram and Facebook only.

const client = filestack.init(YOUR_API_KEY);
const options = {
  fromSources: ["local_file_system","instagram","facebook"],


Sources List

local_file_system yes This is your user’s disk.
url yes Upload file directly from URL.
imagesearch yes Search for images in the File Picker.
facebook yes
instagram yes
googledrive yes
dropbox yes You will need your own OAuth2 application with Dropbox. You can read more about it in our tutorial.
unsplash no Search for free, high quality images from Unsplash community.
webcam no Uses device menu on mobile. Not currently supported in Safari and IE.
video no Uses device menu on mobile. Not currently supported in Safari and IE.
audio no Uses device menu on mobile. Not currently supported in Safari and IE.
box no
github no
gmail no
picasa no
onedrive no
onedriveforbusiness no You will need your own OAuth2 application with OneDrive for Business. You can read more about it in our tutorial.
customsource no This is your S3 bucket as a source. You can find more about it here.
accept array

Using accept array you can specify the types of files that the user is allowed to choose. For example, if you want the user to select images, you can specify ["image/*"] and users would only be able to select images to upload. Similarly, you could specify ["application/pdf"] to only allow PDF documents to be selected.

const client = filestack.init(YOUR_API_KEY);
const options = {
  accept: ["image/*"],


There are multiple formats accepted. For example:

  • .pdf - any file extension
  • image/jpeg - any mime type commonly known by browsers
  • image/* - accept all types of images
  • video/* - accept all types of video files
  • audio/* - accept all types of audio files
  • application/* - accept all types of application files
  • text/* - accept all types of text files

Learn more about all Picker Options from our JavaScript SDK Reference.

Store Options

Picker Store Options interface can be used to control how and where your users files are stored. With Filestack you can choose from multiple storage providers.

storeTo interface

If you choose not to use your own storage provider we will upload files to default Filestack S3 bucket. If you choose to use your own S3 and you configured it in Filestack Developer Portal we will also use it by default.

If you would like to change that behavior and, for example, use different storage provider, or upload files to different path than the default / path you should use storeTo parameter of the Picker Options.

const client = filestack.init(YOUR_API_KEY);
const options = {
    storeTo: {
        location: 'azure',
        path: '/site_uploads/'


Learn more about all Picker Store Options from our JavaScript SDK Reference.


Workflows allow you to wire up conditional logic and image processing to enforce business processes, automate ingest, and save valuable development time. Once you’ve configured a workflow, it can be called with a single reference in your upload code. Learn more about Workflows from our documentation and tutorial.

In order to trigger the workflow job for each upload in the File Picker you need to attach your workflow ID to the storeTo options like this:

const client = filestack.init(YOUR_API_KEY);
const options = {
  storeTo: {
    workflows: [YOUR_WORKFLOW_ID]
picker = client.picker(options);;

Upload Options

Upload Options interface let you control low level details on how files from local file system are uploaded. You can control timeout and retry settings as well as advanced configuration of Filestack’s Content Ingestion Network and Intelligent Ingestion.

You can also define onProgress and onRetry callbacks to improve user experience of your application.

uploadConfig interface

For example, if you would like to change retry logic and timeout settings you can do it like this:

const client = filestack.init(YOUR_API_KEY);
const options = {
    uploadConfig: {
        retry: 5,
        timeout: 60000


Learn more about all Upload Options from our JavaScript SDK Reference.

Upload Tags

Upload Tags allows you to pass custom data (tags) with each file that is uploaded using File Picker. That data specified in the Picker code should have a format of key-value pair and it will be returned in the exact same configuration in the upload response and in the Webhook .

In order to add tags, you need to specify the key-value pair in uploadConfig Picker option:

const client = filestack.init(APIKEY);
const options = {
  uploadConfig: {
    	tags: {
     		"foo": "bar"
  fromSources: ["local_file_system","instagram","facebook"],

The example upload resposne with upload tags:


Please learn more about Upload Tags here.

Transformation Options

Transformation Options interface lets you control how users can manipulate images before they reach out your destination storage.

transformations interface

Currently users can crop, circle and rotate images in the File Picker. You can control them by setting boolean flag and decide whether any of them should be enabled or not. For example:

const client = filestack.init(YOUR_API_KEY);
const options = {
    transformations: {
        crop: false,
        circle: true,
        rotate: true


Learn more about all Transformation Options from our JavaScript SDK Reference.


In order to give you ability to interact with Picker and provide seamless experience for your users we provide following list of callbacks. Most callbacks are part of PickerOptions inteface. Some, like onProgress and onRetry, are part of the UploadOptions interface.

onCancel Called when all uploads in a pick are canceled.
onClose Called when the UI is exited.
onFileSelected Called whenever user selects a file.
onFileUploadFailed Called when uploading a file fails.
onFileUploadFinished Called when a file is done uploading.
onFileUploadProgress Called during multi-part upload progress events. Local files only.
onFileUploadStarted Called when a file begins uploading.
onOpen Called when the UI is mounted.
onUploadDone Called when all files have been uploaded.
onUploadStarted Called when uploading starts (user initiates uploading).
UploadOptions / onProgress Callback for progress events.
UploadOptions / onRetry Callback for retry events.

For example if you would like to verify size of the selected file before upload you can use onFileSelected callback as shown below:

const client = filestack.init(YOUR_API_KEY);

const options = {
    onFileSelected: file => {
        // If you throw any error in this function it will reject the file selection.
        // The error message will be displayed to the user as an alert.
        if (file.size > 1000 * 1000) {
            throw new Error('File too big, select something smaller than 1MB');


Learn more about callbacks from our JavaScript SDK Reference.


In order to make sure that you have full control on who and when opens the Picker and uploads files you can leverage Filestack’s universal security policies mechanism.

To work with the Picker, your policy will need following calls:

pick Ability to open Picker and pick files.
store Ability to store files in your storage destination.
runWorkflows Ability to run workflows after the file is uploaded.

Remember about expiry key which, while optional, is neccessary to provide maximum security and to make your policies TTL reasonably short.

Example policy would look like this:

  "expiry": 1523595600,
  "call": ["pick","store","runWorkflows"],

Having both policy and signature, you can use them in the Picker Client like this:

const clientOptions = {
    security: {
        policy: "eyJleHBpcnkiOiAxNTQ2ODk5NDI4LCAiY2FsbCI6IFsicmVhZCIsICJzdGF0IiwgImNvbnZlcnQiLCAicGljayIsICJzdG9yZSJdfQ==",
        signature: "1fed86599156df046f925e0f773866654a4fc209b0b85b173b5d8088e898b685"

const client = filestack.init(YOUR_API_KEY, clientOptions)

Learn more about Security and other Client Options from our JavaScript SDK Reference.