# Cropper.js — Image Cropping Component for JavaScript

> A lightweight JavaScript library for interactive image cropping with touch support, aspect ratio locking, and canvas-based output.

## Install

Save in your project root:

# Cropper.js — Image Cropping Component for JavaScript

## Quick Use
```bash
npm install cropperjs
```
```js
import Cropper from 'cropperjs';
import 'cropperjs/dist/cropper.css';

const image = document.getElementById('my-image');
const cropper = new Cropper(image, {
  aspectRatio: 16 / 9,
  crop(event) {
    console.log(event.detail.x, event.detail.y);
  }
});
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-de7127d7
Author: AI Open Source