• Public
  • Public/Protected
  • All


  • PickerOptions



Optional accept

accept: string | string[]

Restrict file types that are allowed to be picked. Formats accepted:

  • .pdf <- any file extension
  • image/jpeg <- any mime type commonly known by browsers
  • image/* <- accept all types of images
  • video/* <- accept all types of video files
  • audio/* <- accept all types of audio files
  • application/* <- accept all types of application files
  • text/* <- accept all types of text files

Optional acceptFn

acceptFn: (PickerFileMetadata: any, PickerAcceptFnOptions: any) => Promise<string>

Custom accept check function

acceptFn: (file, options) => {
 return options.mimeFromMagicBytes(file.originalFile).then((res) => { // we can check mimetype from magic bytes
   //console.log(options.mimeFromExtension(file.originalFile.name)); // or check extension from filestack extensions database
   // throw new Error('Cannot accept that file') // we can throw exception to block file upload
   // return Promise.reject('Cannot accept that file'') // or reject a promise
   return Promise.resolve();

Type declaration

    • (PickerFileMetadata: any, PickerAcceptFnOptions: any): Promise<string>
    • Parameters

      • PickerFileMetadata: any
      • PickerAcceptFnOptions: any

      Returns Promise<string>

Optional allowManualRetry

allowManualRetry: boolean

Prevent modal close on upload failure and allow users to retry.

Optional cleanupImageExif

cleanupImageExif: boolean | { keepICCandAPP?: boolean; keepOrientation?: boolean }

Turn on cleaning JPEG image exif. Method can keep image orientation or color profiles

cleanupImageExif: {
  keepOrientation: true
  keepICCandAPP: true

Optional concurrency

concurrency: number

Max number of files to upload concurrently. Default is 4.

Optional container

container: string | Node

Container where picker should be appended. Only relevant for inline and dropPane display modes.

Optional customAuthText

customAuthText: CustomAuthTextOptions

Customize the text on the cloud authentication screen in Picker. Use a cloud source name (see PickerOptions.fromSources) or a 'default' as a key, then put your custom notice or consent to the 'top' or the 'bottom' key to show it respectivly above or under 'Connect button'.

customAuthText: {
  // use it for every cloud authentication screen
  default: {
    top: [
      'default top first line',
      'default top second line'
    bottom: [
      'default bottom first line',
      'default bottom second line'
  // override a default bottom text for only gmail
  gmail: {
    bottom: [
      'We need your permission to access your data and',
      'process it with our machine learning system.'

Optional customSourceContainer

customSourceContainer: string

Set the default container for your custom source.

Optional customSourceName

customSourceName: string

Set the display name for the custom source.

Optional customSourcePath

customSourcePath: string

Set the default path for your custom source container.

Optional customText

customText: PickerCustomText

Provide an object for mapping picker strings to your own strings. Strings surrounded by brackets, { foobar }, are interpolated with runtime values. Source labels are also available to override, e.g. Facebook, Instagram, Dropbox, etc.

Optional disableStorageKey

disableStorageKey: boolean

When true removes the hash prefix on stored files.

Optional disableThumbnails

disableThumbnails: boolean

Disables local image thumbnail previews in the summary screen.

Optional disableTransformer

disableTransformer: boolean

When true removes ability to edit images.

Optional displayMode

displayMode: PickerDisplayMode

Picker display mode, one of 'inline', 'overlay', 'dropPane' - default is 'overlay'.

Optional dropPane

Configure the drop pane behavior, i.e. when displayMode is dropPane.

Optional errorsTimeout

errorsTimeout: number

Timeout for error messages

Optional exposeOriginalFile

exposeOriginalFile: boolean

When true the originalFile metadata will be the actual File object instead of a POJO

Optional fromSources

fromSources: string[]

Valid sources are:

  • local_file_system - Default
  • url - Default
  • imagesearch - Default
  • facebook - Default
  • instagram - Default
  • googledrive - Default
  • dropbox - Default
  • webcam - Uses device menu on mobile. Not currently supported in Safari and IE.
  • video - Uses device menu on mobile. Not currently supported in Safari and IE.
  • audio - Uses device menu on mobile. Not currently supported in Safari and IE.
  • box
  • github
  • gmail
  • googlephotos
  • onedrive
  • onedriveforbusiness
  • customsource - Configure this in your Filestack Dev Portal.
  • unsplash

Optional globalDropZone

globalDropZone: boolean

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

Optional hideModalWhenUploading

hideModalWhenUploading: boolean

Hide the picker modal UI once uploading begins. Defaults to false.

Optional imageDim

imageDim: [number, number]

Specify image dimensions. e.g. [800, 600]. Only for JPEG, PNG, and BMP files. Local and cropped images will be resized (upscaled or downscaled) to the specified dimensions before uploading. The original height to width ratio is maintained. To resize all images based on the width, set [width, null], e.g. [800, null]. For the height set [null, height], e.g. [null, 600].

Optional imageMax

imageMax: [number, number]

Specify maximum image dimensions. e.g. [800, 600]. Only for JPEG, PNG, and BMP files. Images bigger 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.

Optional imageMin

imageMin: [number, number]

Specify minimum image dimensions. e.g. [800, 600]. Only for JPEG, PNG, and BMP files. Images smaller than the specified dimensions will be upscaled 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.

Optional lang

lang: string

Sets locale. Accepts: ca, da, de, en, es, fr, he, it, ja, ko, nl, no, pl, pt, sv, ru, vi, zh, tr

Optional maxFiles

maxFiles: number

Maximum number of files allowed to upload. Defaults to 1.

Optional maxSize

maxSize: number

Restrict selected files to a maximum number of bytes. (e.g. 10 * 1024 * 1024 for 10MB limit).

Optional minFiles

minFiles: number

Minimum number of files required to start uploading. Defaults to 1.

Optional modalSize

modalSize: [number, number]

Specify [width, height] in pixels of the desktop modal.

Optional onCancel

Called when all uploads in a pick are cancelled.

Optional onClose

onClose: () => void

Called when the UI is exited.

Type declaration

    • (): void
    • Returns void

Optional onFileCropped

onFileCropped: PickerFileCallback

Called when file is cropped in picker

Optional onFileSelected

onFileSelected: PickerFileCallback

Called whenever user selects a file.


// Using to veto file selection
// 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.
onFileSelected(file) {
  if (file.size > 1000 * 1000) {
    throw new Error('File too big, select something smaller than 1MB');

// Using to change selected file name
// NOTE: This currently only works for local uploads
onFileSelected(file) {
  // It's important to return a new file by the end of this function.
  return { ...file, name: 'foo' };

The callback function can also return a Promise to allow asynchronous validation logic. You can pass a file object to resolve for changing the file name, it will behave the same as when the file is returned from the non-async callback.

onFileSelected(file) {
  return new Promise((resolve, reject) => {
    // Do something async
    // Or reject the selection with reject()

Optional onFileUploadCancel

onFileUploadCancel: PickerFileCancelCallback

Called when a file upload has been canceled.

Optional onFileUploadFailed

onFileUploadFailed: PickerFileErrorCallback

Called when uploading a file fails.

Optional onFileUploadFinished

onFileUploadFinished: PickerFileCallback

Called when a file is done uploading.

Optional onFileUploadProgress

onFileUploadProgress: PickerFileProgressCallback

Called during multi-part upload progress events. Local files only.

Optional onFileUploadStarted

onFileUploadStarted: PickerFileWithTokenCallback

Called when a file begins uploading.

Optional onOpen

onOpen: (handle: PickerInstance) => void

Called when the UI is mounted.


application handle

Type declaration

Optional onUploadDone

Called when all files have been uploaded.

Optional onUploadStarted

Called when uploading starts (user initiates uploading).

Optional pasteMode

pasteMode: { pasteToFirstInViewPort?: boolean; pasteToFirstInstance?: boolean }

Specify which Picker instance should respond to paste event. By default only hovered instance responds to event.


If none instance is hovered take first picker instance fully visible in viewport


If none instance is hovered take first picker instance that is initialized


is checked first

Type declaration

  • Optional pasteToFirstInViewPort?: boolean
  • Optional pasteToFirstInstance?: boolean

Optional rootId

rootId: string

Define a unique id for the application mount point. May be useful for more advanced use cases. For example, if you wish to have more than one picker instance open at once, then each will need their own unique rootId.

Note: This option is ignored when displayMode is dropPane.

Optional startUploadingWhenMaxFilesReached

startUploadingWhenMaxFilesReached: boolean

Whether to start uploading automatically when maxFiles is hit. Defaults to false.

Optional storeTo

Options for file storage.

Optional supportEmail

supportEmail: string

set support email to display in case of error

Optional transformations

Specify options for images passed to the crop UI.

Optional uploadConfig

uploadConfig: UploadOptions

Options for local file uploads.

Optional uploadInBackground

uploadInBackground: boolean

Start uploading immediately on file selection. Defaults to true.


The feature is can be enabled only if crop is disabled - disableTransformer: true

Optional useSentryBreadcrumbs

useSentryBreadcrumbs: boolean

Use Sentry Breadcrumbs mechanism to log information about occured errors. It can override global objects like console, error etc. Defaults to true.

Optional videoResolution

videoResolution: string

Sets the resolution of recorded video. One of "320x240", "640x480" or "1280x720". Default is "640x480".

Optional viewType

viewType: "grid" | "list"

Default view type option for file browser