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.

Please Note: Release 0.8.0 deprecated transformations.maxDimensions replaced by imageMax, transformations.minDimensions replaced by imageMin, transformations.crop.circle replaced by transformations.circle and transformations.filters, which are not available at this time.

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.

<script src="https://static.filestackapi.com/v3/filestack.js"></script>

Note: Semantic versioning can be implemented for production environments. The current version is: https://static.filestackapi.com/v3/filestack-0.8.1.js

<script type="text/javascript">
  var client = filestack.init('yourApiKey');
  client.pick(pickerOptions);
</script>

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.

Example Pick Code

Pick a max of 5 images
client.pick({ accept: 'image/*', maxFiles: 5, imageMax: [1024, 1024] }).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
Security: {policy: YOUR_POLICY, signature: YOUR_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
  • url - default
  • evernote
  • flickr
  • box
  • github
  • gmail
  • picasa
  • onedrive
  • clouddrive
  • webcam
  • video
  • audio
  • customsource

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.

Note: In order to use Custom Source you will need to have a paid plan and enable S3 Source in your Developer Portal .

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'
  • Hebrew: 'he'
  • 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.

Max image dimensions
Array
imageMax: [width, height]

Specify maximum image dimensions. e.g. : {imageMax: [800, 600]}. Images larger than the specified dimensions will be resized to the maximum size while maintaining the original aspect ratio. The output will not be exactly 800x600 unless the imageMax matches the aspect ratio of the original image.

Min image dimensions
Array
imageMin: [width, height]

Specify minimum image dimensions. e.g. : {imageMin: [800, 600]}. Images smaller than the specified dimensions will be resized to the minimum size while maintaining the original aspect ratio. The output will not be exactly 800x600 unless the imageMin matches the aspect ratio of the original image.

Specify image dimensions
Array
imageDim: [width, height]

Specify image dimensions. e.g. : {imageDim: [800, 600]}. Images smaller than the specified dimensions will be resized to the minimum size while maintaining the original aspect ratio. Images larger than the specified dimensions will be resized to the maximum size while maintaining the original aspect ratio.

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 Thumbnails
Boolean
disableThumbnails: false

The picker will show thumbnails for local image files by default. Some users may wish to disable these thumbnails to avoid performance issues with large images. You can disable local image thumbnails by setting disableThumbnails: true.

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.

Reject the Promise returned by pick on user cancel
Boolean
rejectOnCancel: false

Setting rejectOnCancel to true will reject the Promise returned by pick if the user cancels the upload.

Set resolution for video recording.
string
videoResolution: '640x480'

Specify resolution of recorded video. Options are '320x240', '640x480', or '1280x720'.

Define Custom Source Path
String
customSourcePath: '/myfiles/foldername'

Define the default folder which will be used as the root path in the CustomSource (S3) option.

Specify Custom Source Bucket
String
customSourceContainer: 'myBucket'

Specify the name of the bucket to be used for your CustomSource (S3) option.

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.

circle crop
Boolean
transformations: { 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 aspectRatio is 1. Default value is true.

rotate
Boolean
transformations: { rotate: true }

Set whether a user should be able to rotate their image from within the transformer UI. Default value is true.

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)

force crop
Boolean
transformations: { crop: { force: false } }

Setting force crop to true will require all images to be cropped prior to upload.

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'.

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

Accepts an optional dictionary of key-value pairs that specify how the picker should upload local files. This can be used to configure size of parts uploaded as well as retry logic.

partSize
Integer
uploadConfig: { partsize: 6 }

Determines the size of parts uploaded in MB. This parameter will be overwritten if you have Intelligent Ingestion enabled on your API key.

concurrency
Integer
uploadConfig: { concurrency: 3 }

Determines the maximum number of file parts that will be uploaded concurrently.

intelligent
Boolean
uploadConfig: { intelligent: true }

Optional boolean to turn off Intelligent Ingestion for the picker on an API that has the service enabled.

retry
Integer
uploadConfig: { retry: 10 }

Determines the maximum number of times a file part will be retried if it fails during upload.

retryFactor
Integer
uploadConfig: { retryFactor: 2 }

Determines the base factor for exponential backoff on retry.

timeout
Integer
uploadConfig: { timeout: 30000 }

Number of milliseconds to wait before cancelling upload requests.

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 object that contains the filename, mimetype, size in bytes, and source.

onFileUploadStarted
Function
onFileUploadStarted(file)

Called when a file begins uploading. The callback has a file parameter object that contains 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 object that contains 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, an object that contains file metadata (filename, mimetype, size in bytes, and source), and error, the Error instance for this upload.

onUploadStarted
Function
onUploadStarted(files)

Called when the upload begins. This callback has a files parameter array that contains all files selected for upload.

onOpen
Function
onOpen()

Called when the file picker is opened.

onClose
Function
onClose()

Called when the file picker is closed.

onRetry
Function
onRetry(retryCallback)

Called when retry is initiated. The retry logic is configurable in uploadConfig

The callback has 4 parameters: location, parts, filename, and attempt. Location is a string that identifies the part of the upload being retried. Parts is an array of current parts in the point of the upload flow. Filename is a string identifying the name of the file being retried. Attemp is an integer that gives the number of the current retry.

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.

originalFile

An object containig the properties of the original local 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".

Deprecated Parameters
Parameters that are no longer used in the current release
minDimensions
Deprecated
transformations: { minDimensions: }

This parameter has been deprecated. Please use imageMin for release 0.8.0 and greater.

maxDimensions
Deprecated
transformations: { maxDimensions: }

This parameter has been deprecated. Please use imageMax for release 0.8.0 and greater.

filters
Deprecated
transformations: { filters: }

This parameter has been deprecated and is not available for release 0.8.0 and greater.