CropperJS is a comprehensive JavaScript image cropping library that provides extensive image manipulation capabilities including move, zoom, rotate, and scale operations with precise control over image dimensions and aspect ratios. It offers both a JavaScript API and a web component-based approach with zero external dependencies and cross-browser compatibility.
npm install cropperjsimport Cropper from 'cropperjs';For CommonJS:
const Cropper = require('cropperjs');For utility functions and components:
import { isString, CROPPER_CANVAS, CropperImage } from 'cropperjs';import Cropper from 'cropperjs';
// Create a cropper instance from an image element
const image = document.querySelector('#image');
const cropper = new Cropper(image, {
container: document.querySelector('#container'),
template: '<cropper-canvas><cropper-image></cropper-image></cropper-canvas>'
});
// Get cropper elements
const canvas = cropper.getCropperCanvas();
const cropperImage = cropper.getCropperImage();
const selection = cropper.getCropperSelection();CropperJS is built around several key components:
Cropper class for programmatic control and integration<cropper-canvas>, <cropper-image>, etc.) for declarative usageCore JavaScript interface for creating and managing cropper instances. Provides programmatic access to all cropping functionality.
class Cropper {
static version: string;
element: HTMLImageElement | HTMLCanvasElement;
options: CropperOptions;
container: Element;
constructor(
element: HTMLImageElement | HTMLCanvasElement | string,
options?: CropperOptions
);
getCropperCanvas(): CropperCanvas | null;
getCropperImage(): CropperImage | null;
getCropperSelection(): CropperSelection | null;
getCropperSelections(): NodeListOf<CropperSelection> | null;
}
interface CropperOptions {
container?: Element | string;
template?: string;
}Interactive canvas container that handles user interactions including touch, mouse, and wheel events for cropping operations.
class CropperCanvas extends CropperElement {
background: boolean;
disabled: boolean;
scaleStep: number;
themeColor: string;
$setAction(action: string): this;
$toCanvas(options?: CanvasOptions): Promise<HTMLCanvasElement>;
}
interface CanvasOptions {
width?: number;
height?: number;
beforeDraw?: (context: CanvasRenderingContext2D, canvas: HTMLCanvasElement) => void;
}Advanced image transformation capabilities including rotation, scaling, translation, and matrix-based transformations.
class CropperImage extends CropperElement {
rotatable: boolean;
scalable: boolean;
skewable: boolean;
translatable: boolean;
initialCenterSize: string;
$ready(callback?: (image: HTMLImageElement) => unknown): Promise<HTMLImageElement>;
$move(x: number, y?: number): this;
$rotate(angle: number | string, x?: number, y?: number): this;
$zoom(scale: number, x?: number, y?: number): this;
$transform(a: number, b: number, c: number, d: number, e: number, f: number): this;
}Crop selection areas with precise control over dimensions, aspect ratios, and interactive handles.
class CropperSelection extends CropperElement {
x: number;
y: number;
width: number;
height: number;
aspectRatio: number;
movable: boolean;
resizable: boolean;
zoomable: boolean;
$change(x: number, y: number, width?: number, height?: number, aspectRatio?: number): this;
$toCanvas(options?: CanvasOptions): Promise<HTMLCanvasElement>;
}Comprehensive set of utility functions for type checking, event handling, DOM manipulation, and mathematical operations.
// Type checking
function isString(value: unknown): value is string;
function isNumber(value: unknown): value is number;
function isElement(node: unknown): node is Element;
// Event handling
function on(target: EventTarget, types: string, listener: EventListenerOrEventListenerObject): void;
function off(target: EventTarget, types: string, listener: EventListenerOrEventListenerObject): void;
function emit(target: EventTarget, type: string, detail?: unknown): boolean;
// Geometry utilities
function getOffset(element: Element): { left: number; top: number };
function multiplyMatrices(matrix: number[], ...args: number[][]): number[];Specialized cropping interface elements including interactive handles, grid overlays, crosshairs, shading, and viewer functionality.
class CropperHandle extends CropperElement {
action: string;
plain: boolean;
themeColor: string;
}
class CropperGrid extends CropperElement {
bordered: boolean;
columns: number;
covered: boolean;
rows: number;
themeColor: string;
}
class CropperCrosshair extends CropperElement {
centered: boolean;
themeColor: string;
}
class CropperShade extends CropperElement {
x: number;
y: number;
width: number;
height: number;
themeColor: string;
$change(x: number, y: number, width?: number, height?: number): this;
$reset(): this;
$render(): this;
}
class CropperViewer extends CropperElement {
resize: string;
selection: string;
}// Element tag names
const CROPPER_CANVAS: string;
const CROPPER_IMAGE: string;
const CROPPER_SELECTION: string;
const CROPPER_HANDLE: string;
const CROPPER_GIRD: string;
const CROPPER_CROSSHAIR: string;
const CROPPER_SHADE: string;
const CROPPER_VIEWER: string;
// Action constants
const ACTION_MOVE: string;
const ACTION_SCALE: string;
const ACTION_ROTATE: string;
const ACTION_SELECT: string;
const ACTION_NONE: string;
const ACTION_TRANSFORM: string;
// Event constants
const EVENT_ACTION: string;
const EVENT_ACTION_START: string;
const EVENT_ACTION_END: string;
const EVENT_ACTION_MOVE: string;
const EVENT_CHANGE: string;
const EVENT_TRANSFORM: string;const DEFAULT_TEMPLATE: string;Default HTML template containing the complete cropper structure with canvas, image, selection, handles, and grid elements.