Cropper.js React

A modern, lightweight React wrapper for Cropper.js v2.

Features

- ⚛️ React 18+ Support: Built for modern React applications.
- 📦 Cropper.js v2: Fully embraces the Web Components architecture of Cropper.js 2.0.
- 🧩 Component-Based: Compose your cropper using individual components (CropperCanvas, CropperImage, CropperSelection, etc.) for maximum flexibility.
- 🟦 TypeScript: Fully typed for excellent developer experience.
- 🚀 ESM Only: Modern module format.

Installation

``bash
npm install cropperjs-react-wrapper cropperjs


or

yarn add cropperjs-react-wrapper cropperjs

or

pnpm add cropperjs-react-wrapper cropperjs

or

bun add cropperjs-react-wrapper cropperjs
`

Usage

$3

Compose the components to build your cropping interface. This gives you full control over the layout and behavior.

`tsx
import React from 'react';
import {
CropperCanvas,
CropperImage,
CropperSelection,
CropperHandle,
CropperGrid,
CropperCrosshair,
} from 'cropperjs-react-wrapper';

const App = () => {
return (


);
};

export default App;
`

$3

The library exports React components that wrap the corresponding Cropper.js 2.0 custom elements:

| Component | Cropper.js Element | Description |
| --- | --- | --- |
| CropperCanvas | | The main container for the cropper. |
| CropperImage | | The image to be cropped. Supports transformations. |
| CropperSelection | | The crop box selection area. |
| CropperGrid | | A grid displayed within the selection. |
| CropperCrosshair | | A crosshair displayed within the selection. |
| CropperHandle | | Interactive handles for resizing or moving the selection. |
| CropperShade | | An overlay shade for the non-selected area. |

$3

You can access the underlying DOM elements and their methods (like $rotate, $scale, $toCanvas) using React refs.

`tsx
import { useRef } from 'react';
import { CropperImage, type CropperImageElement } from 'cropperjs-react-wrapper';

const App = () => {
const imageRef = useRef(null);

const handleRotate = () => {
imageRef.current?.$rotate('90deg');
};

return (
<>
Rotate


{/ ... /}


);
};
`

Development

$3

- npm run dev: Start the development server (includes a demo app).
- npm run build: Build the library.
- npm run test: Run tests using Vitest.
- npm run lint`: Run linting using Biome.

License

MIT