Skip to content

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
Croppercropperjquery2014DeprecatedA simple jQuery image cropping plugin.
Cropper.jscropperjs-2015ActiveJavaScript image cropper.
jQuery Cropperjquery-cropperjquery + cropperjs2018MaintainingA jQuery plugin wrapper for Cropper.js.

Getting started

Installation

npm

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

sh
npm install cropperjs@next

For a specific package:

sh
npm install @cropper/element-canvas

CDN

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

html
<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.

js
import Cropper from 'cropperjs';

const cropper = new Cropper('#image');
html
<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.

js
import 'cropperjs';

Use on-demand

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

js
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:

PackageVersionDescription
cropperjsVersionThe all-in-one package.
@cropper/elementVersionAn abstract class for constructing Cropper elements.
@cropper/element-canvasVersionA custom canvas element for the Cropper.
@cropper/element-imageVersionA custom image element for the Cropper.
@cropper/element-shadeVersionA custom shade element for the Cropper.
@cropper/element-handleVersionA custom handle element for the Cropper.
@cropper/element-selectionVersionA custom selection element for the Cropper.
@cropper/element-gridVersionA custom grid element for the Cropper.
@cropper/element-crosshairVersionA custom crosshair element for the Cropper.
@cropper/element-viewerVersionA custom viewer element for the Cropper.
@cropper/elementsVersionA series of custom elements for the Cropper.
@cropper/utilsVersionA 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 HTMLElement 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+

Released under the MIT License.