Image crop for your website in minutes

Cropping images in browsers should be intuitive and simple, and we're up to that. Long story short, it’s just great and way better than firing up a dedicated image editor. Then, there’s a whole bunch of stuff you want to crop: profile photos and backgrounds, avatars, thumbnails, scans, docs or piles of gallery images.

This tutorial is about letting your users to crop images on upload with Uploadcare Widget. It works on any image you throw at us. And, it’s simple to implement without digging into all sorts of things including frameworks, languages, and code bases. Technically, image crop runs on CDN API, you may want to learn more here.

Here's what you'll get:

Uploadcare Widget crop preview

We’re all about killing out the mundane, so here are the 3 quick steps to get you up and running.

Step 1: Have an Uploadcare account

To start with, sign up for a free account. For new users, projects are created automatically. Just make sure to know where your public and secret project keys are. Also, consider having the autostore option turned on (it’s the default.) Otherwise, you’ll have to use our REST API or libs & plugins to handle your files.

Technically, creating an account is not a must. For testing purposes, you can use demopublickey and demoprivatekey as your Uploadcare public and secret keys respectively.

Step 2: Choose a form to use for cropping

In this step, we’re going to need a form in your web app. So, pick one: it could be a profile edit form, image upload form, etc.

Note, images could come from multiple sources. Those matters are covered in the Upload Sources section of our docs.

Step 3: Integrate Uploadcare

Now, it’s time for Uploadcare Widget to show up. Simply put, it’s the ultimate tool for uploads we offer. It’s got minified and bundled versions and is usually served from our CDN. Here’s how it works:

First, add this to your <head> section:

<script>UPLOADCARE_PUBLIC_KEY = 'your_public_key';</script>
<script src="" charset="utf-8"></script>

Next, think of a place on your form where you’d like our widget to appear and add this <input> there.

Note, value can be either empty or contain a UUID/CDN link of an image. In case it’s empty, the widget will let you pick a file from upload sources. Otherwise, you’ll go directly to the preview step and be able to crop an image you defined. The difference here is that in the first case you select a file which then gets uploaded to your project and shown on a preview tab. The second case is when your image has already been uploaded to a project for which you’ve specified UPLOADCARE_PUBLIC_KEY in your <head> section.


Use the code above or your form helpers to build such <input>. Experiment with the value attribute to check out how to preload images to the widget.

Now, that’s a kind of widget you get. This one’s got a preloaded image:

Once you’re done cropping, your image gets updated with the crop CDN API operation. Our widget then passes that URL to the input, and if your form gets submitted, that URL goes to backend. So, technically, your original image goes to our storage, while the widget outputs its version processed in real time with our CDN API crop operation.

That’s how it might look like:,500/cropout.jpg

You can set the cropping behavior of your widget by specifying the data-crop attribute. Like, you could set aspect ratios, dimensions, and stuff.

That’s it — Yoo-hoo!

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 the widget to your liking. We’d be happy to have your pull requests, too.


We're always happy to help with code or other questions you might have! Search our site for more information or send us an email!