Pick

The latest version of the Filestack picker has only one method for uploading files, pick. The picker can be configured to allow multiple uploads, store or not store copies of selected files, transform images and more. By default the pick method will make a copy of each file and store it either in Filestack's storage or the cloud storage option you have configured for your account.

Please Note: The picker will not upload without a valid API key. To initialize the client use filestack.init("yourApiKey"). Filestack's documentation examples include a key in the background, but if you want to test something using your own key, you can always add var client = filestack.init("yourApiKey"); to the live code examples.

Syntax

The pick function can be called at anytime in order to display the Picker dialog once the client has been initialized. You may pass in an optional dictionary of key-value pairs to customize the behavior of the picker.

Note: Security policies and signatures should be included as options when the client is initialized with your API key if your account has security enabled.

Note: Version 0.5.0 of the v3 library contains breaking changes. The functionality and parameter names have changed for the transform options in the pick method.

Note: There have been some changes to our Upload API. If you are encountering an error relating to the storeTo: { location: } parameter, you must either supply this storeTo option with your picker options, or you can upgrade to the latest version of the v3 library which handles this automatically.

<script src="https://static.filestackapi.com/v3/filestack-0.6.3.js"></script>
<script type="text/javascript">
  var client = filestack.init('yourApiKey', { policy: 'policy', signature: 'signature' });
  client.pick(pickerOptions);
</script>

The new Upload API requires that your S3 bucket have proper CORS rules configured. Details on adding the proper CORS configuration to your S3 bucket can be found here: S3 Cors Configuration

Example Pick Code

Pick a max of 5 images
client.pick({ accept: 'image/*', maxFiles: 5, storeTo: { location: 's3' } }).then(function(result) { console.log(JSON.stringify(result.filesUploaded)) })

Parameters

Client Initialization Options
An optional dictionary of key-value pairs that influence the Filestack client.
Security
Object
policy: POLICY, signature: SIGNATURE

If you have security enabled, you will need to initialize the client with 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

pickerOptions
An optional dictionary of key-value pairs that specify how the picker behaves.
Accept
String or Array of Strings
accept: 'image/*'
accept: ['image/*', '.pdf', 'video/mp4', …]

Specify the type of file that the user is allowed to pick. This can be an extension or a mimetype. 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 '.docx' to only allow Word Documents to be selected.

You can also specify an array of mimetypes and extensions to allow the user to select a file from any of the given types.

Picker Sources
String or Array of Strings
fromSources: 'facebook'
fromSources: ['facebook','box',…]

Specify which sources are displayed on the left panel, and in which order, by name.

Sources labeled default will be shown if no value is set for fromSources.

Be sure that the sources you select are compatible with the mimetype(s) or extension(s) specified in the accept parameter.

Currently, Filestack supports the following sources:

  • local_file_system - default
  • imagesearch - default
  • facebook - default
  • instagram - default
  • googledrive - default
  • dropbox - default
  • evernote
  • flickr
  • box
  • github
  • gmail
  • picasa
  • onedrive
  • clouddrive
  • webcam

For all new applications, it is required to set your own Dropbox OAuth keys in order to use Dropbox with Filestack. More info

Note: The webcam source will not work on sites that are not secure (https). Safari and IE do not support the webcam source.

Language
String
lang: 'en'

Specify the language to use in the picker for menus, buttons and prompts. If not set, it will use the language detected in the browser. If the detected language is unavaliable, the default value is 'en'.

Supported languages:

  • English: 'en'
  • German: 'de'
  • Spanish: 'es'
  • French: 'fr'
  • Italian: 'it'
  • Dutch: 'nl'
  • Danish: 'da'
  • Polish: 'pl'
  • Portuguese: 'pt'
  • Russian: 'ru'
  • Chinese: 'zh'
  • Japanese: 'ja'

Are we missing a language you need? If you would like to help us add a translation for any language, please Contact Us.

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" or (10*1024*1024).

Max Files
Integer
maxFiles: 1

Specify the maximum number of files that the user can upload at a time. If the user tries to upload more files than this limit, they will be presented with an error message. By default, maxFiles is set to 1.

Min Files
Integer
minFiles: 1

Specify a minimum amount of files a user must select before their upload can complete. If the user tries to fewer than this limit, they will be presented with an error message. By default, minFiles is set to 1.

Note: If you set minFiles, you must also set maxFiles.

Force Upload When Max Files Reached
Boolean
startUploadingWhenMaxFilesReached: false

Uploads will start immediately after the user reaches the maxFiles limit. By default this is set to false.

Hide When Uploading
Boolean
hideWhenUploading: false

Hides the modal immediately after file is selected or upload button is pressed. The upload will continue in the background and progress events will continue to be fired as the upload happens. By default this is set to false.

Disable Background Uploading
Boolean
uploadInBackground: true

The picker begins uploading files in the background once they are selected in order to provide the fastest and most fluid experience to users. This is the default. However, you can prevent it from uploading anything until the user clicks upload by setting uploadInBackground: false.

Disable Transformer UI
Boolean
disableTransformer: false

The picker offers users the ability to crop, rotate and manipulate their images in various ways by default. If you would prefer that your users not have this ability, you can set disableTransformer: true.

Generate Symbolic Links When Possible
Boolean
preferLinkOverStore: false

Setting preferLinkOverStore to true makes the picker produce symbolic links to where files are originally stored on the web if it is possible (uploads from the local file system are always copies and not symbolic). In the case where a symbolic link is generated, files can be deleted or lost. For example, if a file originally came from Facebook, a user could delete it from their account or change the permissions on the post it was attached to and break your Filestack link to the file. But, in the case of a document selected from Dropbox for instance, you will always have the latest version of that document, which has its benefits depending on your use case. This setting is false by default, which means the standard behavior of the picker is to make a copy of the file.

transformations
An optional dictionary of key-value pairs that specify how the Transformation UI behaves.
transformations
Object
transformations: { parameter: value }

Accepts an optional dictionary of key-value pairs that specify whether the transform UI should be available to the user and what options the user should be presented with therein.

minDimensions
Array
transformations: { minDimensions: [200, 300] }

Minimum dimensions for picked image. Image will be upscaled if smaller. (e.g. [200, 300])

maxDimensions
Array
transformations: { maxDimensions: [200, 300] }

Maximum dimensions for picked image. Image will be downscaled if smaller. (e.g. [200, 300])

crop
Object or Boolean
transformations: { crop: true }

Accepts an optional dictionary of key-value pairs that specify whether the user should be able to crop their images and what options the user should be presented with therein. Default value is true, but you can also pass an object with the following parameters for configuring the cropping area.

crop aspect ratio
Ratio
transformations: { crop: { aspectRatio: ratio } }

The ratio (width to height) to lock for the crop area (e.g. 16/9)

circle crop
Boolean
transformations: { crop: { circle: true } }

Set whether a user should be able to use the circle cropping on their image from within the transformer UI. Can only be combined with aspectRatio when apectRatio is 1. Default value is true.

filters
Array
transformations: { filters: ['sepia','monochrome'] }

Set whether a user should be able to use the sepia and monochrome filters on their image from within the transformer UI. Default value has both filters enabled.

storeTo
An optional dictionary of key-value pairs that specify how the picker stores files.
storeTo
Object
storeTo: { parameter: value }

Accepts an optional dictionary of key-value pairs that specify how the picker should store files once they are selected for upload. If you are using the storeTo parameter and include the container parameter then your storeTo object must include location, container and region.

Location
String
storeTo: { location: 's3' }

Where to store the file. The default is 's3'. Other options are 'azure', 'dropbox', 'rackspace' and 'gcs'. You must have configured your storage in the developer portal to enable this feature. Note: Rackspace, Azure, Dropbox and Google Cloud are only available on the Grow and higher plans.

Path
String
storeTo: { path: '/myfiles/1234.png' }

The path to store the file at within the specified file store. For S3, this is the key where the file will be stored at. By default, Filestack stores the file at the root at a unique id, followed by an underscore, followed by the filename, for example "3AB239102DB_myphoto.png".

If the provided path ends in a '/', it will be treated as a folder, so if the provided path is "myfiles/" and the uploaded file is named "myphoto.png", the file will be stored at "myfiles/909DFAC9CB12_myphoto.png", for example.

IMPORTANT: If the maxFiles parameter is greater than one, be sure to only use paths that end in '/' or else all uploaded files will be written to the same object in your bucket. In other words, the files will overwrite each other.

Container
String
storeTo: { container: 'user-photos' }

The bucket or container in the specified file store where the file should end up. This is especially useful if you have different containers for testing and production and you want to use them both on the same Filestack app. If this parameter is omitted, the file is stored in the default container specified in your developer portal.

Note: This parameter does not apply to the Dropbox file store.

Region
String
storeTo: { region: 'us-east-1' }

The region where your storage container is located. This setting currently applies only to S3 buckets. If you are using a different bucket and region than the one you set up in your developer portal you can pass the region as part of your store options. If this parameter is not set we will do our best to determine the region your S3 bucket is located so that we can properly authenticate our connection request. You can find a list of the S3 regions here: in the "region" column.

Public Access
String
storeTo: { access: 'public' }

Indicates that the file should be stored in a way that allows public access going directly to the underlying file store. For instance, if the file is stored on S3, this will allow the S3 url to be used directly. This has no impact on the ability of users to read from the Filestack file URL. Defaults to 'private'.

Callback Functions
Functions that are called at various points during the upload process
onFileSelected
Function
onFileSelected(file)

Called whenever user selects a file. The callback has a file parameter which is an object containing the filename, mimetype, size in bytes, and source.

onFileUploadStarted
Function
onFileUploadStarted(file)

Called when a file begins uploading. The callback has a file parameter which is an object containing the filename, mimetype, size in bytes, and source.

onFileUploadProgress
Function
onFileUploadProgress(file, progressEvent)

Called during multi-part upload progress events. Progress events fire on every XHR progress event, but these progress events will not fire while background uploads are happening. They will also not fire for files selected from cloud sources like google drive. They only fire for files selected from the local file system.

The callback has two parameters, file which is an object containing file metadata (filename, mimetype, size in bytes, and source) and the progressEvent which contains the following:

totalPercent The percent (as an integer) of the file that has been uploaded.
totalBytes An integer stating the total number of bytes uploaded for this file.
onFileUploadFinished
Function
onFileUploadFinished(file)

Called when a file is done uploading. The callback has a file parameter which is an object containing the filename, mimetype, size in bytes, and source.

onFileUploadFailed
Function
onFileUploadFailed(file, error)

Called when uploading a file fails. The callback has two parameters, file which is an object containing file metadata (filename, mimetype, size in bytes, and source), and error which is the Error instance for this upload.

onClose
Function
onClose()

Called when the modal is closed.

Picker Response Data
Metadata returned by the picker
filename

The name of the file that was uploaded.

handle

The Filestack file handle. This is useful because other Filestack methods accept handles as their input.

mimetype

The mimetype of the file, if available.

originalPath

This field is reported by the picker at the time the file is uploaded. It is the location where the file was selected from. This can be the location in a user's local file system, or the id or path reported by a cloud drive.

size

The size of the file in bytes, if available. We will attach this directly to the returned metadata when we have it, otherwise you can always get the size by calling client.retrieve(filestackHandle, { metadata: true })

source

The source the file was uploaded from. This could be "local_file_system", "instagram", "dropbox" or any other source.

url

The Filestack URL that points to the uploaded file.

key

If the file was stored in one of the file stores you specified or configured (S3, Rackspace, Azure, etc.), the key will tell you where in your storage container this file was placed.

container

If the file was stored in one of the file stores you specified or configured (S3, Rackspace, Azure, etc.), the container will be the bucket/container the file was placed in.

status

The status of the upload. This is not returned if the Filestack link is a symbolic link. Possible statuses are "Stored", "InTransit", and "Failed". "InTransit" means the file has not yet been copied to your bucket, but the Filestack link will still be valid and won't change once the file's status changes to "Stored". If the status returned is other than "Stored", and you have configured webhooks, you will receive a webhook when the status changes to "Stored".