--- sidebar: auto --- # 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](https://github.com/fengyuanchen/cropper) | [`cropper`](https://www.npmjs.com/package/cropper) | [`jquery`](https://www.npmjs.com/package/jquery) | 2014 | Deprecated | A simple jQuery image cropping plugin. | | [Cropper.js](https://github.com/fengyuanchen/cropperjs) | [`cropperjs`](https://www.npmjs.com/package/cropperjs) | - | 2015 | Active | JavaScript image cropper. | | [jQuery Cropper](https://github.com/fengyuanchen/jquery-cropper) | [`jquery-cropper`](https://www.npmjs.com/package/jquery-cropper) | [`jquery`](https://www.npmjs.com/package/jquery) + [`cropperjs@1`](https://www.npmjs.com/package/cropperjs) | 2018 | Maintaining | A jQuery plugin wrapper for Cropper.js 1.0. | ## Getting Started ### Installation #### npm npm is the recommended installation method when building large-scale applications with Cropper.js. ```sh npm install cropperjs ``` For a specific package: ```sh npm install @cropper/element-canvas ``` #### CDN For prototyping or learning purposes, you can use the latest version with: ```html ``` 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'; // import { createCropper } from 'cropperjs'; const cropper = new Cropper('#image'); // const cropper = createCropper('#image'); ``` ```html Picture ``` #### Use in DOM Import all Cropper elements from the `cropperjs` package and [define](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define) them as custom elements automatically. ```js import 'cropperjs'; ``` :::live-demo ```html ``` ::: #### Use on-demand Import the required Cropper elements only and [define](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/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(); ``` :::live-demo ```html ``` ::: ## Packages Cropper.js contains a series of [npm](https://www.npmjs.com/) packages: | Package | Version | Description | | --- | --- | --- | | `cropperjs` | [![Version](https://img.shields.io/npm/v/cropperjs)](https://www.npmjs.com/package/cropperjs) | The all-in-one package. | | `@cropper/element` | [![Version](https://img.shields.io/npm/v/@cropper/element)](https://www.npmjs.com/package/@cropper/element) | An abstract class for constructing Cropper elements. | | `@cropper/element-canvas` | [![Version](https://img.shields.io/npm/v/@cropper/element-canvas)](https://www.npmjs.com/package/@cropper/element-canvas) | A custom canvas element for the Cropper. | | `@cropper/element-image` | [![Version](https://img.shields.io/npm/v/@cropper/element-image)](https://www.npmjs.com/package/@cropper/element-image) | A custom image element for the Cropper. | | `@cropper/element-shade` | [![Version](https://img.shields.io/npm/v/@cropper/element-shade)](https://www.npmjs.com/package/@cropper/element-shade) | A custom shade element for the Cropper. | | `@cropper/element-handle` | [![Version](https://img.shields.io/npm/v/@cropper/element-handle)](https://www.npmjs.com/package/@cropper/element-handle) | A custom handle element for the Cropper. | | `@cropper/element-selection` | [![Version](https://img.shields.io/npm/v/@cropper/element-selection)](https://www.npmjs.com/package/@cropper/element-selection) | A custom selection element for the Cropper. | | `@cropper/element-grid` | [![Version](https://img.shields.io/npm/v/@cropper/element-grid)](https://www.npmjs.com/package/@cropper/element-grid) | A custom grid element for the Cropper. | | `@cropper/element-crosshair` | [![Version](https://img.shields.io/npm/v/@cropper/element-crosshair)](https://www.npmjs.com/package/@cropper/element-crosshair) | A custom crosshair element for the Cropper. | | `@cropper/element-viewer` | [![Version](https://img.shields.io/npm/v/@cropper/element-viewer)](https://www.npmjs.com/package/@cropper/element-viewer) | A custom viewer element for the Cropper. | | `@cropper/elements` | [![Version](https://img.shields.io/npm/v/@cropper/elements)](https://www.npmjs.com/package/@cropper/elements) | A series of custom elements for the Cropper. | | `@cropper/utils` | [![Version](https://img.shields.io/npm/v/@cropper/utils)](https://www.npmjs.com/package/@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](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement) interface. | | `CropperCanvas` | `CropperElement` | The `CropperCanvas` interface provides properties and methods for manipulating the layout and presentation of `` elements. | | `CropperImage` | `CropperElement` | The `CropperImage` interface provides properties and methods for manipulating the layout and presentation of `` elements. | | `CropperShade` | `CropperElement` | The `CropperShade` interface provides properties and methods for manipulating the layout and presentation of `` elements. | | `CropperHandle` | `CropperElement` | The `CropperHandle` interface provides properties and methods for manipulating the layout and presentation of `` elements. | | `CropperSelection` | `CropperElement` | The `CropperSelection` interface provides properties and methods for manipulating the layout and presentation of `` elements. | | `CropperGrid` | `CropperElement` | The `CropperGrid` interface provides properties and methods for manipulating the layout and presentation of `` elements. | | `CropperCrosshair` | `CropperElement` | The `CropperCrosshair` interface provides properties and methods for manipulating the layout and presentation of `` elements. | | `CropperViewer` | `CropperElement` | The `CropperViewer` interface provides properties and methods for manipulating the layout and presentation of `` 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+