Skip to content
Back to Blog

Image cropping for web apps with Uploadcare

Valentin Golev

Feb 8, 2017 10:00:00 AM

Cropping from inside the browser is great: it's intuitive and simpler than loading a dedicated image editor. You can crop profile photos, graphics for user profile backgrounds or headers, and any sort of gallery images.

However, adding crop functionality to your uploads or existing images is but another mundane task to deal with, eating up time better spent on new ideas. Try Googling javascript image crop right now. There will be 30+ solutions and even blog posts attempting to describe them as vaguely as possible. What's worse, when you finally pick one that better suits your language and framework of choice, you're confronted with a very specific API, so good luck integrating it into your existing code base.

Everything we do at Uploadcare is directed at combating the mundane. Amongst other things, we offer image crop as SaaS. It will work with any image you throw at us, as long as it has a public URL. You only have to take 4 easy steps and we'll take care of the rest.

Step 1: Register an Uploadcare project

Visit our signup page and register in one easy step. You can use your GitHub or Google accounts for secure one-click sign in.

Upon signup you'll be forwarded to your profile page with your starting information. Your Uploadcare public and private keys are listed in a large font - make a note of them for later.

Step 2: Choose a form for cropping

We're going to need a form in your application we can then enhance with the cropping function, say, a profile edit form. You don't need to enable file uploads (i.e. multipart data), as we simply need the source URL and can integrate cropping in any HTML form.

Step 3: Integrate Uploadcare

We provide a cropping widget served from CloudFlare CDN with guaranteed uptime. Of course you can also download it and serve from your own domain, if you wish to do so.

To apply the widget to your form, add this to the bottom of the <head> section:

<script>UPLOADCARE_PUBLIC_KEY = 'your_public_key';</script>
<script src=""></script>

Next, place this tag anywhere on your form, where you'd like the cropping widget to appear.


Copy and paste this code, or create an input like this with your form helpers. Be sure to replace original_image_url with an actual URL of the image you'd like to crop.

Now your form should have a widget like this:



The cropped image will automatically be hosted on our CDN. The UUID of this image will be submitted with your form as the value of the input field you added (named your_form_field_name in the sample code above).

You can restrict the way cropping is done with the data-crop attribute, by specifying the desired aspect ratio, as well as the minimum and maximum size, by use of automatic scaling. These options are fully described in widget documentation.

Step 4: Accept the cropped image

In your form submission handle you should have received an UUID (mentioned above). This is the UUID of the cropped version of the image stored on our CDN. It has a publicly-accessible URL:

This is a permalink that can replace the original image URL, where 3addab78-6368-4c55-ac08-22412b6a2a4c is the UUID.

But the image is not automatically available at this URL after a user submits the form. You need to acknowledge that it should be made public, by sending an HTTP request:

POST /files/image_uuid/storage/ HTTP/1.1
Authorization: Uploadcare.Simple your_public_key:your_private_key

It's a simple POST with a special Authorization header. Of course image_uuid, your_public_key, and your_private_key should be replaced with their real values.

Alternatively, there are Uploadcare libraries for a number of programming languages and frameworks that will do this storage request for you.

That's it!

You've just given your users the ability to crop images, and without breaking a sweat. Well done.

The widget you've seen is also open source. If you're not satisfied with it out of the box, feel free to fork around it and change it to your liking. And we're also always happy to receive pull requests.


Uploadcare provides file uploading, storage, processing and content delivery network for any web site or mobile app. It is very simple to integrate, so you can spend less time and money on development and maintenance, reducing it from weeks and months to days and hours. Uploadcare utilizes resources of Amazon S3, Amazon CloudFront and CloudFlare, providing on-the-fly image processing and many social sources (like Facebook or Dropbox) to choose files from.

Valya Golev is a Russian web developer who has been programming since the age of six. In programming he above all values simplicity, and detests all repeated frustrations. After several years of programming websites of varying complexity at Whitescape, he now wishes to help programmers from around the world develop comfortable, reliable and beautiful websites with greater speed and consistency.

Written By:

Valentin Golev

Want to get our totally not sh*tty weekly newsletter?

Sometimes The Wayfarer is funny, sometimes insightful, but always the least spammy newsletter this side of Tatooine.