Crop Widget - instantiate the CropUI with a simple HTML tag

Give your uers the power to crop the images they upload. The conversion is performed in the browser using Canvas API.


Pass an existing Filestack link to the cropping tool

<input data-fp-button-class="btn btn-primary"
  name="myName" />

Additional Options

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

Your API key. If you've already called filepicker.setKey() elsewhere in your code, this isn't needed


Required: The url of the image you want the user to crop.


Your API key. If you've already called filepicker.setKey() elsewhere in your code, this isn't needed

Button Text

The text to show on the button. Defaults to "Pick File".

Button Class

The class(es) to be applied to the button for styling, for example "btn btn-primary"


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.


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.

Custom CSS

Allow a user to set a custom CSS file to load for the Filestack dialog by providing the https publicly accessible url for a CSS file. 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 Dialog 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}}


The HMAC-SHA256 Filestack security signature. Read more about security and how to generate policies and signatures


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 fpfile or fpfiles (for multiple mode) attribute with information about the uploaded files (jQuery users: look under event.originalEvent).

Client side image compression and resize

Note: client side compression and resizing relies on the dialog being opened to work. If a user utilizes the drop-pane functionality (meaning no modal dialog window opens) to upload their images, their images will not be modified.

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

Image Quality

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.

Image Dimensions

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". See more.

Image Max Dimensions

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. See more.

Image Minimum Dimensions

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. See more.

Crop UI

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


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

Crop Ratio

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. See more.

Crop Dimensions

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. See more.

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. See more.

Crop Min

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

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. See more.

Store Options

Store Location

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. S3, Rackspace, Azure, Dropbox and Google Cloud Storage are only available on paid plans.

Store Path

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

Store Container

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.

Store Region

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.

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