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

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

Basic Example

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

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

const App = () => {
  return (
    <div style={{ width: '100%', height: 400 }}>
      <CropperCanvas background>
        <CropperImage
          src="https://fengyuanchen.github.io/cropperjs/images/picture.jpg"
          alt="Picture"
          rotatable
          scalable
          skewable
          translatable
        />
        <CropperSelection initialCoverage={0.5} movable resizable zoomable>
          <CropperGrid role="grid" covered bordered />
          <CropperCrosshair centered />
          <CropperHandle action="move" themeColor="rgba(255, 255, 255, 0.35)" />
          <CropperHandle action="n-resize" />
          <CropperHandle action="e-resize" />
          <CropperHandle action="s-resize" />
          <CropperHandle action="w-resize" />
          <CropperHandle action="ne-resize" />
          <CropperHandle action="nw-resize" />
          <CropperHandle action="se-resize" />
          <CropperHandle action="sw-resize" />
        </CropperSelection>
      </CropperCanvas>
    </div>
  );
};

export default App;

Components

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

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

Accessing Methods

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

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

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

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

  return (
    <>
      <button onClick={handleRotate}>Rotate</button>
      <CropperCanvas>
        <CropperImage ref={imageRef} src="..." />
        {/* ... */}
      </CropperCanvas>
    </>
  );
};

Development

Commands

• 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