JavaScript File Picker

Getting Started

To start with Web File Picker you will need Filestack application and API key. Please read our Getting Started 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="//static.filestackapi.com/filestack-js/1.x.x/filestack.min.js"></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);
client.picker().open();

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": "https://cdn.filestackcontent.com/AFrHW1QRsWxmu5ZLU2qg",
  "uploadId": "cfcc198e63b7328c17f09f1af519fcdf",
  "originalFile": {
    "name": "myfile",
    "type": "image/png",
    "size": 1277297
  },
  "status": "Stored"
}

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:

{
   "filesUploaded":[
      {
         "filename":"myfile.png",
         "handle":"AFrHW1QRsWxmu5ZLU2qg",
         "mimetype":"image/png",
         "originalPath":"picker_transformation.png",
         "size":1277297,
         "source":"local_file_system",
         "url":"https://cdn.filestackcontent.com/AFrHW1QRsWxmu5ZLU2qg",
         "uploadId":"cfcc198e63b7328c17f09f1af519fcdf",
         "originalFile":{  
            "name":"myfile",
            "type":"image/png",
            "size":1277297
         },
         "status":"Stored"
      }
   ],
   "filesFailed":[

   ]
}

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"],
};

client.picker(options).open();

Sources List

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/*"],
};

client.picker(options).open();

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/'
	}
};

client.picker(options).open();

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

workflowsinterface

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);
picker.open();

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
	}
};

client.picker(options).open();

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

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
    }
};

client.picker(options).open();

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

Callbacks

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.

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');
		}
	}
};

client.picker(options).open();

Learn more about callbacks from our JavaScript SDK Reference.

Security

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:

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)
client.picker().open();

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