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/3.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"
}
PARAM | TYPE | DESCRIPTION |
---|---|---|
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:
{
"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
SOURCE | DEFAULT | DESCRIPTION |
---|---|---|
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. |
yes | ||
yes | ||
googledrive | yes | |
dropbox | yes | You will need your own OAuth2 application with Dropbox. You can read more about it in our tutorial. |
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. |
clouddrive | no | This is Amazon Cloud Drive. |
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/*"],
};
client.picker(options).open();
There are multiple formats accepted. For example:
.pdf
- any file extensionimage/jpeg
- any mime type commonly known by browsersimage/*
- accept all types of imagesvideo/*
- accept all types of video filesaudio/*
- accept all types of audio filesapplication/*
- accept all types of application filestext/*
- 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.
workflows
interface
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.
CALLBACK | DESCRIPTION |
---|---|
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');
}
}
};
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:
CALL | DESCRIPTION |
---|---|
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)
client.picker().open();
Learn more about Security and other Client Options from our JavaScript SDK Reference.