Widget crop options

  • This documentation is for the version 3.6.0 of the widget. If you're looking for the widget v2 docs, check here.

Uploadcare Widget features many crop options including free crop. You can add the crop feature to your widget by enabling this option. This alters the usual widget behavior. Now, after users select their images for uploading, they encounter a step where cropping can be applied.

That works as follows: original files go to an Uploadcare project associated with a public key you set for your widget; crop is applied as the crop image processing operation by modifying the original URLs.

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

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, and 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 are 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"
  data-crop=""
/>

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"
  data-crop="4:3"
/>

Fixed size with upscaling,

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

We’re always happy to help with code, integration, and other stuff. Search our site for more info or post your question in our Community Area.