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.

<script src="https://static.filestackapi.com/v3/filestack-0.4.2.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

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

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

transformOptions
An optional dictionary of key-value pairs that specify how the Transformation UI behaves.
transformOptions
Object
transformOptions: { 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
transformOptions: { minDimensions: [200, 300] }

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

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

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

crop
Object or Boolean
transformOptions: { 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 parameter for configuring the cropping area.

{ crop: { aspectRatio: ratio } } The ratio (width to height) to lock for the crop area (e.g. 16/9)
rotate
Boolean
transformOptions: { transformations: { rotate: false } }

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

circle
Boolean
transformOptions: { transformations: { circle: false } }

Set whether a user should be able to use the circle transformation on their image from within the transformer UI. Default value is false.

monochrome
Boolean
transformOptions: { transformations: { monochrome: false } }

Set whether a user should be able to use the monochrome transformation on their image from within the transformer UI. Default value is false.

sepia
Boolean
transformOptions: { transformations: { sepia: false } }

Set whether a user should be able to use the sepia transformation on their image from within the transformer UI. Default value is false.

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 path, container, or access; then your storeTo object must include location, path, container and access. The region parameter is always optional.

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.

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.

totalProgressPercent The percent (as an integer) of total upload complete
progressTotal The total number of bytes uploaded thus far across all parts.
part The part being referenced by this specific progress event.
loaded The amount of data in this part that has been uploaded.
byteLength An integer stating the total number of bytes in this part.
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.