Cropper.js — Image Cropping Component for JavaScript

Introduction

Cropper.js provides an interactive image cropping experience directly in the browser. Users can drag, zoom, rotate, and resize the crop region on any image element, and developers can extract the result as a canvas element or blob for upload. It is commonly used in profile photo editors, content management systems, and image processing workflows.

What Cropper.js Does

• Adds an interactive crop overlay to any image element in the page
• Supports zoom, rotate, flip, and free-form or fixed-ratio cropping
• Outputs cropped results as Canvas, Blob, or data URL
• Handles touch gestures for mobile cropping
• Provides a responsive mode that scales with container size changes

Architecture Overview

Cropper.js wraps the target image element in a container and overlays a draggable crop box rendered with CSS transforms. User interactions (drag, pinch, scroll) update an internal data model that stores position, dimensions, and rotation. When the developer calls getCroppedCanvas(), the library draws the cropped region onto an off-screen canvas element using the original image data, respecting rotation and scale, and returns the canvas for further processing or export.

Setup & Configuration

• Install from npm or load via CDN; import the JS module and CSS stylesheet
• Create a Cropper instance by passing an image element and options
• Set aspectRatio for fixed ratios (e.g., 1 for square, 16/9 for widescreen)
• Use viewMode (0-3) to control crop-box movement boundaries
• Call cropper.getCroppedCanvas().toBlob(callback) to extract the result

Key Features

• Supports 27 configuration options and 10 methods for full control
• Multiple view modes from free movement to strict container bounds
• Built-in rotate and flip transformations
• Cross-origin image support via the checkCrossOrigin option
• Minimal footprint with no external dependencies

Comparison with Similar Tools

• react-image-crop — React-specific crop component; Cropper.js is framework-agnostic with richer features
• FilePond Image Crop — tied to the FilePond upload pipeline; Cropper.js works standalone
• Fabric.js — full canvas manipulation library; Cropper.js is purpose-built for cropping and much lighter
• tui-image-editor — full image editor with filters and drawing; heavier than Cropper.js for crop-only needs

FAQ

Q: Can I use Cropper.js with React or Vue? A: Yes. Use it via refs or choose wrapper libraries like react-cropper for idiomatic component integration.

Q: Does Cropper.js support mobile devices? A: Yes. It handles touch events for drag, pinch-to-zoom, and rotation on mobile browsers.

Q: How do I get the cropped image as a file for upload? A: Call cropper.getCroppedCanvas().toBlob(blob => { /* upload blob */ }) to get a Blob suitable for FormData upload.

Q: Can I crop to a circular shape? A: Cropper.js always crops to a rectangle. For a circular result, apply a CSS border-radius: 50% to the output canvas or mask it on the server side.

Sources

• https://github.com/fengyuanchen/cropperjs
• https://fengyuanchen.github.io/cropperjs/