Image Cropping Interface

Gives your users the power to crop the images they upload. Conversions are performed in the browser using the Canvas API. Crop UI is avaliable in both single and multiple file mode. To crop previously uploaded images use the filepicker.processImage() method.

To include the Crop UI in the picker add the 'CONVERT' service to the services list. 'CONVERT' is included by default. You can also include the 'conversions' parameter to include rotate and filter functions in addition to the cropping tool: {conversions: ['crop', 'rotate', 'filter']}

Syntax

The javascript processImage() function can be called using a blob or filestack url as the input. You may pass in an optional dictionary of key-value pairs to customize the options of the crop dialog. Handler functions are also optional, and can be passed in as callback functions for the events onSuccess, and onError.

An additional note on browser support, the Crop UI works on desktop and mobile browsers that support the Canvas API.

<script src="https://api.filestackapi.com/filestack.js"></script>
<script type="text/javascript">
  filepicker.setKey("your_API_KEY");
  filepicker.processImage(input, convert_options, onSuccess(Blob){}, onError(FPError){});
</script>
input
the file to crop
Input
string or blob
{Filestack blob or url}

A Blob or Filestack URL pointing to the image you would like to crop. If you have a external url you need to use the filepicker.store call to first generate a Blob

convert_options
optional dictionary of key-value pairs that determine how the cropper behaves
Conversions
Array
{conversions: ['crop', 'rotate', 'filter']}

When used in conjunction with the 'CONVERT' service, the conversions array allows you to specify what functions are available in the UI for the user. Include 'crop' to allow the user to crop an image, include 'rotate' to allow a user to rotate the uploaded image left or right, include filter to allow user to blur or sharpen the uploaded image. You can include all the services or a selection of the three. If 'CONVERT' is specified, but no conversions are set, the default behavior is to display the cropping tool only.

Crop ratio
Double
{cropRatio: 4/3}

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.

Crop area dimensions
Array
{cropDim: [width, height]}

Specify a crop area with fixed dimenions. e.g. : {cropDim: [800, 600]}. The user will only be allowed to move the crop area. If the image is smaller than the specified dimensions the crop area will fill the image.

Max crop dimensions
Array
{cropMax: [width, height]}

Specify the maximum dimensions of the crop area. e.g. : {cropMax: [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.

Min crop dimensions
Array
{cropMin: [width, height]}

Specify crop area minimum dimensions. e.g. : {cropMin: [400, 300]}. Can be used together with cropMax and cropRatio

Force to crop
Boolean
{cropForce: true}

If set to true, the user will have to crop all images before uploading them. This works for both single and multiple files mode but no if 'hide' option is set to true. By default set to false.

onSuccess
The function to call if a file is picked successfully.

We'll return a Blob as a JSON object with the following properties.

url The main Filestack file url on which all other operations are based.
filename The filename of the uploaded file.
mimetype The mimetype of the uploaded file.
size The size of the uploaded file in bytes, if available.
isWriteable Whether the file can be written to using filepicker.write.

Sample response

{
    "url":"https://cdn.filestackcontent.com/Knu33RNOQ6qi0S5ND1mY",
    "filename":"calvinhobbes2.jpg",
    "mimetype":"image/jpeg",
    "size":71644,
    "cropped":{
      "originalImageSize":[720,540],
      "cropArea":{"position":[0,0],"size":[720,540]}
    },
    "converted":true,
    "id":1,
    "client":"computer",
    "isWriteable":true
}
onError
The function to call if there is an error when picking a file.

Possible error codes on the FPError:

101 The user closed the dialog without picking a file
400 Bad parameters were passed to the server. This often will be the case when you turned on security but haven't passed up a policy or signature.
403 Invalid request - The policy and/or signature don't allow you to make this request. For more information see Security Documentation.

For more info about FPErrors, see Error Handling.

Sample response

{"code":101}

Crop function example

Load existing Filestack image into picker to crop, rotate, or add filters
var url = document.getElementById('crop_basic_results_export').src; filepicker.processImage( url, { conversions: ['rotate', 'crop', 'filter'] }, function(Blob){ console.log(JSON.stringify(Blob)); var image = document.getElementById("crop_basic_results_export"); image.src = Blob.url; } );

Crop Ratio

{cropRatio: 4/3}

Specify crop area ratio. Can be a float, an integer or a ratio like 4/3 or 16/9. By default not specifed.

Restrict resizing crop area to a specific ratio
var url = document.getElementById('crop_ratio_results_export').src; filepicker.processImage( url, { cropRatio: 4/3, }, function(Blob){ console.log(JSON.stringify(Blob)); var image = document.getElementById("crop_ratio_results_export"); image.src = Blob.url; } );

Crop Area Dimensions

{cropDim: [width, height]}

Specify a crop area with fixed dimenions. e.g. : {cropDim: [800, 600]}. The user will only be allowed to move the crop area. If the image is smaller than the specified dimensions the crop area will fill the image.

Restrict crop area size to a specific set of dimensions
var url = document.getElementById('crop_dim_results').src; filepicker.processImage( url, { cropDim: [400, 300], }, function(Blob){ console.log(JSON.stringify(Blob)); var image = document.getElementById("crop_dim_results"); image.src = Blob.url; } );

Max Crop Dimensions

{cropMax: [width, height]}

Specify the maximum dimensions of the crop area. e.g. : {cropMax: [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.

Min Crop Dimensions

{cropMin: [width, height]}

Specify crop area minimum dimensions. e.g. : {cropMin: [400, 300]}. Can be used together with cropMax and cropRatio

Restrict crop area size to a range of dimensions
var url = document.getElementById('crop_min_results').src; filepicker.processImage( url, { cropMin: [300, 200], cropMax: [600, 400], }, function(Blob){ console.log(JSON.stringify(Blob)); var image = document.getElementById("crop_min_results"); image.src = Blob.url; } );