Guide · Open source
How to use Cropper.js: install and add image cropping
Updated · written with AI from the project's own documentation and checked against our catalogue data
Cropper.js is a JavaScript image cropper: a library that shows an image on a web page with an adjustable crop box so a user can select the part they want. This guide is for web developers who want to add that cropping interface to a site or web app. After reading it, you will know what the project is, how to get the source, and where to find the details you need to wire it in.
Cropper.jsfengyuanchen/cropperjs · ★ 13.9k · MIT Install options & downloads Quick start
- 1Confirm you need a library. Decide whether you are building cropping into your own site or app. Cropper.js is a code library, so it requires development work.
- 2Check your Node.js setup. Make sure Node.js is installed. The README does not state a minimum version, so confirm requirements on the project website.
- 3Clone the repository. Run git clone https://github.com/fengyuanchen/cropperjs.git to get the source.
- 4Pick the right branch. Use the v2.x code this README describes, or the separate v1 branch if your project depends on the v1.x API.
- 5Read the project website. Open https://fengyuanchen.github.io/cropperjs/ for usage details, since the README points there for documentation.
- 6Add the cropper to your page. Follow the website's guidance to show an image with a crop box and read the selected area in your code.
What Cropper.js does
Cropper.js lets a page display an image with a crop box that the user can adjust. The user chooses which part of the picture to keep, and your code handles the cropping interface.
It is a code library, not a finished app. You add it to your own website or web application. If you want a ready-made cropping tool for end users without writing code, this project is not that.
Prerequisites: Node.js and JavaScript or TypeScript
The project is written in TypeScript and is aimed at teams already working in JavaScript or TypeScript. The README lists Node.js as a prerequisite but does not state which Node.js version is required, so check the project website or package files before you start.
- Node.js installed on your machine
- Familiarity with JavaScript or TypeScript and a web page or app to add cropping to
Get the Cropper.js source
The README gives a git clone command for the repository. Run it in the folder where you want the project to live.
This README covers the v2.x branch. If your project needs the v1.x API, the README points to a separate v1 branch instead, so make sure you use the branch that matches your needs.
git clone https://github.com/fengyuanchen/cropperjs.gitFind the usage details on the project website
The README is brief and mostly points to the project website at https://fengyuanchen.github.io/cropperjs/ for details. Use the website as the main reference for how to initialise the cropper on an image and how to read the selected crop area.
The README also links to npm, where the package is published as cropperjs, so you can check the package page for installation details.
- Project website: https://fengyuanchen.github.io/cropperjs/
- npm package page: cropperjs
Choose between Cropper.js and wrapper libraries
If your front end uses a framework, you may prefer a wrapper built for it. The README lists related projects, including react-cropper and vue-cropperjs, and mentions a React wrapper that is compatible with v2.
Other options in the same space include react-image-crop. Compare them on the features your project needs, and check each project's own documentation for its API and licence.
- react-cropper (React)
- vue-cropperjs (Vue)
- angular-cropperjs (Angular)
- ember-cropperjs (Ember)
- cropperjs-react-wrapper (React, compatible with v2)
What people use it for
- Letting users crop a profile photo before uploading it to a web app
- Adding a crop step to an image upload form on a website
- Building an image editing screen inside a JavaScript or TypeScript front end
- Using a framework wrapper such as react-cropper or vue-cropperjs in a React or Vue project
Frequently asked questions
Is Cropper.js free to use?
Yes. The README states that the project is licensed under the MIT License. Check the LICENSE file in the repository for the full terms.
What do I need to install Cropper.js?
The README lists Node.js as a prerequisite but does not state a version. It gives a git clone command for the repository, and the npm package is named cropperjs.
Is Cropper.js an app I can use without coding?
No. The README describes it as a JavaScript image cropper library. It is meant for developers who add cropping to a website or web app.
Which version does this README cover?
It covers the v2.x branch. The README says v1.x lives on a separate v1 branch, so projects that need the v1.x API should use that branch.
What are alternatives to Cropper.js?
The README lists related projects such as react-cropper, vue-cropperjs and angular-cropperjs. Other libraries such as react-image-crop are also used for image cropping. Compare them on your framework and needs.
Where can I find the full documentation?
The README is brief and points to the project website at https://fengyuanchen.github.io/cropperjs/ for details.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Cropper.js suits web developers and teams working in JavaScript or TypeScript who need a free, MIT-licensed cropping component for a site or app. It is not suitable for non-developers who want a ready-made cropping tool, and projects that need the v1.x API should use its separate branch or another library.
Install options & downloads