Image crop for your web app in 20 minutes

Cropping in the broswer is great: it's intuitive and much easier for users than firing up a dedicated image editor. You can crop profile photos, graphics for user profile backgrounds or headers, or just a bunch of gallery images.

Adding crop facilities to your uploads or existing images, however, is yet another mundane task, eating up you time better spent on building unique things. Try Googling for javascript image crop right now. There will be 30+ solutions and even blog posts trying to describe them in a vague manner. What's worse, when you finally pick one that better suits your language and framework of choice, you're still confronted with an imaginative API. Good luck trying to figure out how to integrate it in your existing code base.

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

Step 1: Register an Uploadcare project

Visit our signup page for a single-step registration. You can also use your GitHub or Google accounts for secure one-click sign in.

Upon signup you'll be forwarded to your profile page with a bit of information. Most importantly, your Uploadcare public and private keys are listed in a large font. We're going to need these later.

Step 2: Choose a form to use for cropping

We're going to need a form in your application that we'll enrich with the cropping function. It could be a profile edit form, for example. You don't need to enable file uploads (i.e. multipart data), as we simply need the source URL and thus 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 always download it and serve from your own domain, if you like.

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

<script>UPLOADCARE_PUBLIC_KEY = 'your_public_key';</script>
<script src="" charset="utf-8"></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 such an input with your form helpers. Be sure to replace original_image_url with an actual URL to 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 minimum and maximum size with 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 source image that is stored on our CDN. It has a publicly-accessible URL like this one:

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

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

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

So, it's a simple POST with a special Authorization header. Of course, image_uuid, your_public_key, and your_private_key should be respectfully replaced with their real values that you already know.

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

That's it!

You've just allowed your users to crop images, without breaking a sweat. Well done.

The widget you've just seen is also open source. If you're not satisfied with what's out of the box, feel free to fork and change to your liking. We'd be happy to have your pull requests, too.

If you haven't found what you were looking for in these docs, try looking in our Knowledge Base.