Saving Image Bandwidth

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

It is common that you don’t want hi-res original images uploaded to your Uploadcare account. Doing so is inefficient on both ends:

  • Sending large images over mobile networks can be expensive for your users.
  • Large images take up your account storage limit and delivering those increase your traffic.

To handle the issue, Uploadcare Widget implements client-side image optimization via the data-image-shrink option.

The option is passed into your widget as a string holding your preferred resolution and, optionally, a JPEG quality of the resulting image. The preferred resolution you provide does not affect original image aspect ratio.

Image Shrink outputs to:

  • JPEG in case an input image has no transparency.
  • PNG in case an input image includes transparent pixels.

Here are some examples of values you can specify for data-image-shrink to control the feature:

  • 800x600, shrinks images to 0.48 megapixels with the default JPEG quality of 80%.
  • 1600x1600 95%, shrinks images to 2.5 megapixels with the JPEG quality set to 95%.

The resolution you set for optimized images should not exceed 5 megapixels. All EXIF info from your original images will be copied to the resized ones. The copied EXIF info includes image orientation, camera model, geolocation, and settings.

Input images will not be optimized in the following cases:

  • When a client browser does not support all the required APIs.
  • When images are uploaded from social media or URLs.
  • If the original resolution / target resolution ratio falls behind 2.0. For example, you can not shrink a 2560x1560px (4 MP) image to 1600x1600px (2.5 MP) while this works with a 2448x3264px (8 MP) original. The reason we implemented this limit is to preserve an optimal balance between a decline in quality and drop in file size.

Live Examples

Resize to 1024x1024px on a client

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

Resize multiple files to 640x640px on a client

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