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?
TypeCropper.js 1.0Cropper.js 2.0
Created20152021
StatusMaintainingActive
Package Number112+
ArchitectureAll in oneModular
Browser CompatibilityModern browsers / IE 9+Modern browsers
ExtensibleNoYes
CustomizableNoYes
CSS-in-JSNoYes
Import on-demandNoYes
Multiple selectionsNoYes
Rotate image on touchNoYes
  • What is the difference between Cropper, Cropper.js, and jQuery Cropper?
GitHub Projectnpm PackageDependenciesCreatedStatusDescription
Cropperopen in new windowcropperopen in new windowjqueryopen in new window2014DeprecatedA simple jQuery image cropping plugin.
Cropper.jsopen in new windowcropperjsopen in new window-2015ActiveJavaScript image cropper.
jQuery Cropperopen in new windowjquery-cropperopen in new windowjqueryopen in new window + cropperjsopen in new window2018MaintainingA 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 defineopen in new window them as custom elements automatically.

import 'cropperjs';

Use on-demand

Import the required Cropper elements only and defineopen in new window 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 npmopen in new window packages:

PackageVersionDescription
cropperjsVersionopen in new windowThe all-in-one package.
@cropper/elementVersionopen in new windowAn abstract class for constructing Cropper elements.
@cropper/element-canvasVersionopen in new windowA custom canvas element for the Cropper.
@cropper/element-imageVersionopen in new windowA custom image element for the Cropper.
@cropper/element-shadeVersionopen in new windowA custom shade element for the Cropper.
@cropper/element-handleVersionopen in new windowA custom handle element for the Cropper.
@cropper/element-selectionVersionopen in new windowA custom selection element for the Cropper.
@cropper/element-gridVersionopen in new windowA custom grid element for the Cropper.
@cropper/element-crosshairVersionopen in new windowA custom crosshair element for the Cropper.
@cropper/element-viewerVersionopen in new windowA custom viewer element for the Cropper.
@cropper/elementsVersionopen in new windowA series of custom elements for the Cropper.
@cropper/utilsVersionopen in new windowA series of common constants and utility functions for Cropper.

Interfaces

InterfaceInheritsDescription
CropperFunctionThe Cropper constructor creates a new Cropper instance.
CropperElementHTMLElementThe CropperElement interface represents any Cropper element, extends the HTMLElementopen in new window interface.
CropperCanvasCropperElementThe CropperCanvas interface provides properties and methods for manipulating the layout and presentation of <cropper-canvas> elements.
CropperImageCropperElementThe CropperImage interface provides properties and methods for manipulating the layout and presentation of <cropper-image> elements.
CropperShadeCropperElementThe CropperShade interface provides properties and methods for manipulating the layout and presentation of <cropper-shade> elements.
CropperHandleCropperElementThe CropperHandle interface provides properties and methods for manipulating the layout and presentation of <cropper-handle> elements.
CropperSelectionCropperElementThe CropperSelection interface provides properties and methods for manipulating the layout and presentation of <cropper-selection> elements.
CropperGridCropperElementThe CropperGrid interface provides properties and methods for manipulating the layout and presentation of <cropper-grid> elements.
CropperCrosshairCropperElementThe CropperCrosshair interface provides properties and methods for manipulating the layout and presentation of <cropper-crosshair> elements.
CropperViewerCropperElementThe 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+