Customize the Filestack filepicker

Before you call the .pick() function make sure you have placed Filestack in your project with the script tag:

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

Or by installing Filestack-JS using NPM

You will need to instantiate the client with your API key and security or CNAME if they apply to you.

The filepicker is enclosed in one function client.pick()

const client = filestack.init('Your_API_Key',[options]);
client.pick();

By default, the pick function will call default sources, set max uploads to 1, and use Filestack’s storage.

Parameters within the function are highly customizable and can be set to your specific use case.

Once you have your Filepicker instantiated, you can modify the parameters away from the default options and give your users a truly customized uploader.

Picker Options

An optional dictionary of key-value pairs that specify how the picker behaves.

Accepted Filetypes 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 specifyimage/*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
  • onedriveforbusiness
  • clouddrive
  • webcam*
  • video
  • audio
  • customsource*

Note: 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 users will see 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 unavailable, 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 stored, 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.

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.

Prevent modal from closing if upload fails Boolean

allowManualRetry: false

Setting allowManualRetry to true will keep the modal open if any of the uploads fail and present an option for the user to click to re-attempt upload.

Set Root ID of picker String

rootId ='__filestack-picker'

Set the id of the element that mounts the picker.

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.

Toggle Drop Zone Boolean

globalDropZone: false

Toggle the drop zone to be active on all views. Default is active only on local file source.

Access Underlying File Instance Boolean

exposeOriginalFile: false

Can be set to true to ensure that the originalFile metadata will be the actual File object instead of a POJO.

Set Modal Size Array

modalSize: [720, 500]

Specify width and height in pixels of the desktop modal.

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.

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.

Store To

An optional dictionary of key-value pairs that specify how the picker stores files.

Store To 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 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'

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.

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

Upload Config

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 * 1024 * 1024 }

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 (FII) 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: 60000 }

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. They will 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:

  • totalPercentThe percent (as an integer) of the file that has been uploaded.
  • totalBytesAn 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(retryObject)

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

The callback is passed an object with 4 fields: 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. Attempt 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.metadata(handle)
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 containing the properties of the original local file. This will be the actual File instance if “exposeOriginalFile” is true.
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 is valid and won't change once the status changes to 'Stored'. If you have configured webhooks, you will receive a webhook when the status changes to 'Stored'.
uploadId
his string value is a UUID that can be used to track files in callbacks.