Guide

Introduction

Cropper.js 2.0 is a series of web components for image cropping.

• What is the difference between Cropper.js 1.0 and Cropper.js 2.0?

Type	Cropper.js 1.0	Cropper.js 2.0
Created	2015	2021
Status	Maintaining	Active
Package Number	1	12+
Architecture	All in one	Modular
Browser Compatibility	Modern browsers / IE 9+	Modern browsers
Extensible	No	Yes
Customizable	No	Yes
CSS-in-JS	No	Yes
Import on-demand	No	Yes
Multiple selections	No	Yes
Rotate image on touch	No	Yes

• What is the difference between Cropper, Cropper.js, and jQuery Cropper?

GitHub Project	npm Package	Dependencies	Created	Status	Description
Cropper	cropper	jquery	2014	Deprecated	A simple jQuery image cropping plugin.
Cropper.js	cropperjs	-	2015	Active	JavaScript image cropper.
jQuery Cropper	jquery-cropper	jquery + cropperjs	2018	Maintaining	A jQuery plugin wrapper for Cropper.js.

Getting started

Installation

npm

npm is the recommended installation method when building large-scale applications with Cropper.js.

npm install cropperjs@next

For a specific package:

npm install @cropper/element-canvas

CDN

For prototyping or learning purposes, you can use the latest version with:

<script src="https://unpkg.com/cropperjs@next"></script>

For production, we recommend linking to a specific version number and build to avoid unexpected breakage from newer versions.

Usage

Use in JavaScript

Import the Cropper class and constructing a new Cropper instance.

import Cropper from 'cropperjs';

const cropper = new Cropper('#image');

<img id="image" src="/cropperjs/v2/picture.jpg" alt="Picture">

Use in DOM

Import all Cropper elements from the cropperjs package and define them as custom elements automatically.

import 'cropperjs';

Use on-demand

Import the required Cropper elements only and define them as custom elements manually.

import CropperCanvas from '@cropper/element-canvas';
import CropperImage from '@cropper/element-image';
import CropperHandle from '@cropper/element-handle';

CropperCanvas.$define();
CropperImage.$define();
CropperHandle.$define();

Packages

Cropper.js contains a series of npm packages:

Package	Version	Description
cropperjs		The all-in-one package.
@cropper/element		An abstract class for constructing Cropper elements.
@cropper/element-canvas		A custom canvas element for the Cropper.
@cropper/element-image		A custom image element for the Cropper.
@cropper/element-shade		A custom shade element for the Cropper.
@cropper/element-handle		A custom handle element for the Cropper.
@cropper/element-selection		A custom selection element for the Cropper.
@cropper/element-grid		A custom grid element for the Cropper.
@cropper/element-crosshair		A custom crosshair element for the Cropper.
@cropper/element-viewer		A custom viewer element for the Cropper.
@cropper/elements		A series of custom elements for the Cropper.
@cropper/utils		A series of common constants and utility functions for Cropper.

Interfaces

Interface	Inherits	Description
Cropper	Function	The Cropper constructor creates a new Cropper instance.
CropperElement	HTMLElement	The CropperElement interface represents any Cropper element, extends the HTMLElement interface.
CropperCanvas	CropperElement	The CropperCanvas interface provides properties and methods for manipulating the layout and presentation of <cropper-canvas> elements.
CropperImage	CropperElement	The CropperImage interface provides properties and methods for manipulating the layout and presentation of <cropper-image> elements.
CropperShade	CropperElement	The CropperShade interface provides properties and methods for manipulating the layout and presentation of <cropper-shade> elements.
CropperHandle	CropperElement	The CropperHandle interface provides properties and methods for manipulating the layout and presentation of <cropper-handle> elements.
CropperSelection	CropperElement	The CropperSelection interface provides properties and methods for manipulating the layout and presentation of <cropper-selection> elements.
CropperGrid	CropperElement	The CropperGrid interface provides properties and methods for manipulating the layout and presentation of <cropper-grid> elements.
CropperCrosshair	CropperElement	The CropperCrosshair interface provides properties and methods for manipulating the layout and presentation of <cropper-crosshair> elements.
CropperViewer	CropperElement	The CropperViewer interface provides properties and methods for manipulating the layout and presentation of <cropper-viewer> elements.

Browser support

• Edge 79+
• Firefox 63+
• Chrome 54+
• Safari 10.1+
• Opera 41+
• iOS Safari 10.3+
• Android Browser 81+
• Opera Mobile 46+
• Chrome for Android 81+
• Firefox for Android 68+
• Samsung Internet 6.2+