Crop Images via File Uploader UI

  • This is for the version 3.x of the widget. If you're looking for the widget v2 docs, check here
  • Here’s how you migrate from v2 to v3.

Image Crop as Widget Option

Cropping images is such a common task that we decided to implement it right in the File Uploader UI.

Uploadcare Widget features a good bunch of crop options including free crop. Adding the feature to your widget instance is done through implementing the data-crop option. Keep in mind this will alter your widget behavior and hence user experience: a new step gets added to the flow, that’s where users will be able to apply cropping.

This alters the usual widget behavior. Now, after users select their images for uploading, they encounter a step where cropping can be applied.

How Cropping Works

Technically, image cropping works as post-processing via the Image Processing feature:

  • Original images go to an Uploadcare project associated with a Public Key set for your widget instance.
  • Crop is applied as the crop image processing operation by injecting its URL directive into original URLs.
  • The widget returns resulting CDN URLs with injected crop.

Configuring Crop

Crop options are put into the data-crop attribute as a string holding comma-separated crop presets. When you define several presets, users will be able to choose from the related crop options right in the UI.

Each crop preset is a combination of a size or ratio definition and an optional keyword:

  • "disabled", crop is disabled. Can’t be combined with other presets.
  • "" or "free", crop is enabled; users can freely select any crop area on their images.
  • "2:3", any area with the aspect ratio of 2:3 can be selected for cropping.
  • "300x200" — same as above, but if the selected area is greater than 300x200 pixels, the resulting image will be downscaled to fit the dimensions.
  • "300x200 upscale" — same as above, but even if the selected area is smaller, the resulting image gets upscaled to fit the dimensions.
  • "300x200 minimum" — users won’t be able to define an area smaller than 300x200 pixels. If an image we apply our crop to is smaller than 300x200 pixels, it will be upscaled to fit the dimensions.

Crop examples

Free crop

<input type="hidden" role="uploadcare-uploader" name="my_file"

Choosing from predefined aspect ratios

<input type="hidden" role="uploadcare-uploader" name="my_file"
  data-crop="free, 16:9, 4:3, 5:4, 1:1"

Fixed aspect ratio

<input type="hidden" role="uploadcare-uploader" name="my_file"

Fixed size with upscaling

<input type="hidden" role="uploadcare-uploader" name="my_file"
  data-crop="400x300 upscale"