Getting Started

Filestack Architecture

File Upload

File Export (Save To)

Responsive Images

Image Transformations

Document Transformations

Video Transcoding

Audio Transcoding





Filestack Viewer


Supported Cloud Drives

Filestack Recipes

Filestack Integrations

Filestack SDKs

Register for an API key

Pick Widget - instantiate the Filestack dialog with a simple HTML tag

Rather than calling the Filestack from javascript, you can simply put in html widgets that will handle all the interaction for you. The widgets are designed to be drop-in replacements for what you already have, making it even easier to get started

Using the Pick widget, you can automagically turn an ordinary input field into the picker. Once the file is chosen, the input field will be filled in with the url of the chosen file, ready to be sent off to your server.

Note: The picker will not launch without an API key. To set your key use filepicker.setKey("your_API_KEY"). Filestack's documentation examples includes a key in the background or set your key for you if you visit this page directly from the developer portal.

<input type="filepicker" name="myName" />
Sample response
    url: 'https://...',
    data: {
      filename: 'filename.txt',
      size: 100,
      type: 'text/plain'
    url: 'https://...',
    data: {
      filename: 'filename2.jpg',
      size: 9000,
      type: 'image/jpeg'

Additional Options

data-fp-apikey Your API key. If you've already called filepicker.setKey() elsewhere in your code, this isn't needed
data-fp-button-text The text to show on the button. Defaults to "Pick File".
data-fp-button-class The class(es) to be applied to the button for styling, for example "btn btn-primary"
data-fp-mimetype Only files that match this mimetype will be allowed, for example specifying "image/*" will only allow images to be picked
data-fp-mimetypes If you want to allow more than one mimetype, you can specify them as a list, for example "image/png,text/*"
data-fp-extension Only files that match this extension will be allowed, for example specifying ".pdf" will only allow pdf files to be picked. You should not set both extension options and mimetype options. It will not work.
data-fp-extensions If you want to allow more than one extension, you can specify them as a list, for example ".png,.jpeg"
data-fp-language Set the language that should be used for the text inside the picker. For example, use data-fp-language="es" to load the Spanish translation. You can see a full list of possible translations here.
data-fp-container How to load the Filestack dialog. Possible values are "window", "modal", or the id of an iframe in the current document. Defaults to "modal". Using "window" will launch the dialog in its own browser window.

Cloud based files are not copied by default. They remain in their original location and Filestack creates a "symlink". If you wish to have the file copied onto your own storage, you can specify where we should put the copy. The default is S3. Other options are 'azure', 'dropbox', 'rackspace' and 'gcs'. You must have configured your storage options in the developer portal to enable this feature.

Rackspace, Azure, Dropbox and Google Cloud Storage are only available on paid plans.


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 with 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".


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 with the same Filestack API key. If this parameter is omitted, the file is stored in the default container specified in your developer portal.

Note that this parameter does not apply to the Dropbox file store.


The region where your storage container is located. For example: data-fp-store-region="us-east-1". 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 store region as part of your widget 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.

data-fp-store-access Indicates if 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. Options are "public" and "private", defaults to 'private'.
data-fp-multiple If "true", allow the user to select multiple files. The files selected will be written to the input tag field as a comma separated list of the file names. Defaults to "false". (Note: "true" and "false" are strings)
data-fp-maxFiles Specify the maximum number of files that the user can upload at a time. If the user tries to upload more than this, they will be presented with an error message. By default, there is no cap on the number of files a user can select when data-fp-multiple is set to true.
data-fp-openTo Open the Filestack dialog directly to the service set with data-fp-openTo. For example "BOX" will open the picker to Box. To show the open header (set in the developer portal) set the data-fp-openTo value to 'welcome'.
data-fp-service Only allow the user to select a file from the services given by name. For example data-fp-services="BOX"
data-fp-services The list of services to limit selections from by name. The services will be shown in the provided order. An example value might be "BOX,COMPUTER,FACEBOOK". Full list.
data-fp-conversions If you include the CONVERT service in data-fp-services, the cropUI will be enabled. The crop function is on by default (without using the data-fp-conversions parameter) when the CONVERT service is used, but you can also control which extra functions the cropping tool includes by adding the following values "crop,rotate,filter" to the data-fp-conversions parameter. In order to get rotation and cropping you would use data-fp-conversions="crop,rotate", and in order to get all three use data-fp-conversions="crop,rotate,filter".
data-fp-webcam-dim Set the resolution of the images that the Filestack webcam outputs. Image size is limited by the resolution of user's webcam. For example data-fp-webcam-dim="1280, 720".
data-fp-video-recording-resolution Set the resolution of the video that the Filestack webcam outputs from the VIDEO service. There are three possible settings, "320x240", "640x480" and "1280x720". If not set the default is "640x480". For example data-fp-video-recording-resolution="640x480"
data-fp-video-length Set a limit to how long the Video recordings generated by the VIDEO service can be. Values are in seconds. The default is "3600" (60 minutes), the maximum possible value is "5400" (90 minutes). For example data-fp-video-length="3600".
data-fp-audio-length Set a limit to how long the Audio recordings generated by the AUDIO service can be. Values are in seconds. The default is "3600" (60 minutes), the maximum possible value is "5400" (90 minutes). For example data-fp-audio-length="3600"
data-fp-maxSize The maximum file size allowed, in bytes. For example, to make sure files are all less then 10MB, use "10485760" (10*1024*1024).
data-fp-debug Useful when developing, makes it so the widget responds with dummy data immediately when clicked.
data-fp-policy The Filestack security policy. Read more about security and how to generate policies and signatures
data-fp-signature The Filestack security signature. Read more about security and how to generate policies and signatures
onchange When the dialog finishes uploading the file, the javascript code in the onchange field will be run with a special 'event' variable. The variable has a fpfiles (or if not multiple, also fpfile) attribute with information about the files (jQuery users: look under event.originalEvent).
data-fp-background-upload Background uploads are available in multiple mode. Uploads will start immediately after the user selects a file. By default this is set to true.
data-fp-hide Hides the modal immediately after file is selected. The upload will continue in the background and progress callbacks will continue to be fired as the upload happens. By default this is set to false.
data-fp-custom-css Allow a user to set a custom CSS file to load for the Filestack dialog by providing a url. This can be unique to each dialog instance. You can also set a CSS file to load with the Filestack dialog in the developer portal as a global setting that is applied everytime the dialog is loaded using your API key. Custom CSS is a Filestack add-on and is not included in basic plans by default.
data-fp-custom-text Allows a user to provide their own text for the Filestack dialog. Url should use https protocol. Here is a sample JSON file including the English text for the dialog that can be used as a base for your custom text: English_Dialog_Text.JSON Your custom text must include all the keys present in this file. The values can be blank if you choose. Other language files are available by using the language code to modify the url linking to this French translation file, so es.js for Spanish, ru.js for Russian, pl.js for Polish, etc. The sample French file above contains variables that look like this: __variable__, however in order to work with the data-fp-custom-text picker option, these variables must adhere to this format: {{variable}}.

Specify the image quality/compression ratio. Range 0 - 100. 100% quality = 0 compression. By default there is no compression.

Client side image compression and resizing works only for local & webcam images and is available for mobile and desktop devices. See more

data-fp-image-dim Specify image dimenions. e.g. : data-fp-image-dim="800, 600". Local images and webcam stills 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", eg. "800, null". For the height set "null, height", e.g. : "null, 600".
data-fp-image-max Specify maximum image dimenions. e.g. : data-fp-image-max="800, 600". Images bigger than the specified dimensions will be resized to the max size. Works for local and webcam images.
data-fp-image-min Specify minimum image dimenions. e.g. : data-fp-image-min="800, 600". Images smaller than the specified dimensions will be upscaled to the minimum size. Works for local and webcam images.

Specify the crop area height to width ratio. This can be a float, an integer or a ratio like 4/3 or 16/9. By default it is not specifed.

To include the crop UI in a widget add the 'CONVERT' service to the services list. 'CONVERT' is included by default. See more

data-fp-crop-dim Specify the dimensions the image should have after being cropped. Eg. data-fp-crop-dim="800,600". Using cropDim the user is able to resize the crop area within a fixed ratio. The selected area will be resized to the dimensions specified by the cropDim parameter.
data-fp-crop-max Specify the maximum dimensions of the crop area. e.g. : data-fp-crop-max="800, 600". If the image is smaller than the specified dimensions it won't be applied. Can be used in conjunction with cropRatio and cropMin.

data-fp-crop-min Specify crop area minimum dimensions. e.g. : data-fp-crop-max="400, 300". Can be used together with cropMax and cropRatio

data-fp-crop-force If set to true, the user will have to crop all images before uploading them. This works for both single and multiple files mode. By default set to false.