Building a Modern Image Cropper in React with CropperJS 2.x

Israel Merljak — Wed, 08 Oct 2025 23:10:52 +0000

Image cropping is a common requirement in web applications - from profile picture uploads to photo editing tools. While CropperJS has been the go-to library for years, version 2.x brought a complete rewrite using modern web components. This created a gap: the existing react-cropper library only supports v1.x.

In this tutorial, I'll show you how to implement image cropping in React using CropperJS 2.x with full TypeScript support.

Why CropperJS 2.x?

CropperJS 2.x is a ground-up rewrite that leverages modern web standards:

✅ Web Components - Built on native Custom Elements
✅ Better Performance - Optimized rendering and memory usage
✅ Modern Architecture - Cleaner API surface
✅ Framework Agnostic - Works anywhere web components work

However, using web components directly in React requires careful handling of refs, events, and lifecycle management.

Meet react-cropper-2

I built @imerljak/react-cropper-2 to provide idiomatic React bindings for CropperJS 2.x. The library offers three flexible APIs:

Component API - Drop-in React component (easiest)
Hook API - Composable hook with render function
Advanced Hook API - Maximum control for power users

All with full TypeScript support.

Installation

npm install @imerljak/react-cropper-2 cropperjs@2

The library automatically imports and registers CropperJS web components, so you don't need to do it manually.

Quick Start: Component API

The simplest way to get started is using the <Cropper> component:

import { useRef } from 'react';
import { Cropper, type CropperRef } from '@imerljak/react-cropper-2';

function ProfilePicture() {
  const cropperRef = useRef<CropperRef>(null);

  const handleSave = async () => {
    const canvas = await cropperRef.current?.getCroppedCanvas();
    if (canvas) {
      const blob = await new Promise(resolve =>
        canvas.toBlob(resolve, 'image/jpeg', 0.9)
      );
      // Upload blob to your server
      console.log('Ready to upload:', blob);
    }
  };

  return (
    <div>
      <Cropper
        ref={cropperRef}
        src="/profile-photo.jpg"
        alt="Profile picture"
        aspectRatio={1} // Square crop
        onReady={() => console.log('Cropper ready!')}
        onChange={(e) => console.log('Crop changed:', e.detail.bounds)}
      />
      <button onClick={handleSave}>Save</button>
      <button onClick={() => cropperRef.current?.reset()}>Reset</button>
    </div>
  );
}

Live Preview with useCropper Hook

For more control, use the useCropper hook which provides built-in state management:

import { useState } from 'react';
import { useCropper } from '@imerljak/react-cropper-2';

function ImageEditor() {
  const [previewUrl, setPreviewUrl] = useState<string>();

  const { renderCropper, bounds, reset, getCroppedCanvas } = useCropper({
    src: '/my-image.jpg',
    alt: 'Edit me',
    aspectRatio: 16 / 9,
    onChange: async () => {
      // Update preview on every crop change
      const canvas = await getCroppedCanvas();
      setPreviewUrl(canvas?.toDataURL('image/png'));
    },
  });

  return (
    <div className="editor-layout">
      <div className="cropper-section">
        {renderCropper({ style: { maxHeight: '500px' } })}
      </div>

      <div className="preview-section">
        <h3>Preview</h3>
        {previewUrl && <img src={previewUrl} alt="Preview" />}
        {bounds && (
          <pre>
            {JSON.stringify(bounds, null, 2)}
          </pre>
        )}
        <button onClick={reset}>Reset</button>
      </div>
    </div>
  );
}

Advanced: Custom Cropper UI

Need complete control? Use useCropperAdvanced to build custom UIs:

import { useCropperAdvanced } from '@imerljak/react-cropper-2';

function CustomCropper() {
  const {
    canvasRef,
    selectionRef,
    bounds,
    setBounds,
    reset,
  } = useCropperAdvanced({
    autoInitialize: true,
    onReady: () => console.log('Ready!'),
  });

  const setSquareCrop = () => {
    setBounds({ x: 50, y: 50, width: 300, height: 300 });
  };

  return (
    <div>
      <cropper-canvas ref={canvasRef} background>
        <cropper-image
          src="/image.jpg"
          alt="Custom cropper"
          rotatable
          scalable
        />
        <cropper-selection
          ref={selectionRef}
          initial-coverage={0.8}
          movable
          resizable
          outlined
        >
          <cropper-grid role="grid" bordered covered />
          <cropper-handle action="move" />
          <cropper-handle action="n-resize" />
          <cropper-handle action="e-resize" />
          <cropper-handle action="s-resize" />
          <cropper-handle action="w-resize" />
          <cropper-handle action="ne-resize" />
          <cropper-handle action="nw-resize" />
          <cropper-handle action="se-resize" />
          <cropper-handle action="sw-resize" />
        </cropper-selection>
      </cropper-canvas>

      <div className="custom-controls">
        <button onClick={setSquareCrop}>Square Crop</button>
        <button onClick={reset}>Reset</button>
        {bounds && (
          <span>
            {bounds.width}x{bounds.height}
          </span>
        )}
      </div>
    </div>
  );
}

TypeScript Benefits

The library is TypeScript-first with comprehensive type definitions:

import type {
  CropperRef,
  CropperBounds,
  CropperEventHandler,
  GetCroppedCanvasOptions
} from '@imerljak/react-cropper-2';

// Fully typed ref
const cropperRef = useRef<CropperRef>(null);

// Type-safe event handlers
const handleChange: CropperEventHandler = (event) => {
  const { bounds, canvas } = event.detail;
  console.log(`Crop: ${bounds.width}x${bounds.height}`);
};

// Type-safe options
const options: GetCroppedCanvasOptions = {
  width: 800,
  height: 600,
  fillColor: '#fff',
};

Common Use Cases

Avatar Upload with Circular Crop

function AvatarUpload() {
  const cropperRef = useRef<CropperRef>(null);

  const handleUpload = async () => {
    const canvas = await cropperRef.current?.getCroppedCanvas({
      width: 200,
      height: 200,
    });

    if (canvas) {
      const blob = await new Promise<Blob | null>(resolve =>
        canvas.toBlob(resolve, 'image/jpeg', 0.95)
      );

      const formData = new FormData();
      formData.append('avatar', blob!, 'avatar.jpg');

      await fetch('/api/upload-avatar', {
        method: 'POST',
        body: formData,
      });
    }
  };

  return (
    <Cropper
      ref={cropperRef}
      src="/uploaded-photo.jpg"
      aspectRatio={1}
      initialCoverage={0.8}
      rounded // Makes it appear circular
    />
  );
}

Multiple Aspect Ratios

function MultiAspectCropper() {
  const [aspectRatio, setAspectRatio] = useState(16 / 9);

  return (
    <div>
      <div className="aspect-ratio-controls">
        <button onClick={() => setAspectRatio(16 / 9)}>16:9</button>
        <button onClick={() => setAspectRatio(4 / 3)}>4:3</button>
        <button onClick={() => setAspectRatio(1)}>1:1</button>
        <button onClick={() => setAspectRatio(undefined)}>Free</button>
      </div>

      <Cropper
        src="/image.jpg"
        aspectRatio={aspectRatio}
      />
    </div>
  );
}

CORS Image Handling

When cropping images from different domains:

<Cropper
  src="https://example.com/image.jpg"
  crossOrigin="anonymous"
  alt="Remote image"
/>

API Overview

Component Props

Prop	Type	Default	Description
`src`	`string`	required	Image URL
`aspectRatio`	`number`	-	Aspect ratio (e.g., 16/9)
`initialCoverage`	`number`	0.5	Initial crop coverage (0-1)
`background`	`boolean`	true	Show background
`movable`	`boolean`	true	Allow moving selection
`resizable`	`boolean`	true	Allow resizing
`zoomable`	`boolean`	true	Allow zooming
`onReady`	`function`	-	Fires when ready
`onChange`	`function`	-	Fires on crop change

Ref Methods

interface CropperRef {
  getCanvas: () => CropperCanvasElement | null;
  getBounds: () => CropperBounds | null;
  setBounds: (bounds: Partial<CropperBounds>) => void;
  reset: () => void;
  clear: () => void;
  getCroppedCanvas: (options?) => Promise<HTMLCanvasElement | null>;
}

Live Examples

Check out the interactive Storybook documentation with live examples covering:

Basic cropping scenarios
Different aspect ratios
Custom styling
Event handling patterns
All three API approaches
Advanced configurations

Browser Support

Works in all modern browsers that support:

ES2020
Web Components (Custom Elements)
ES Modules

Comparison with react-cropper (v1)

If you're coming from react-cropper (v1.x wrapper):

Feature	react-cropper	react-cropper-2
CropperJS version	1.x	2.x
Architecture	jQuery-based	Web Components
TypeScript	Partial	Full, strict mode
React 19	❌	✅
Bundle size	Larger	Smaller
APIs	1 (component)	3 (component + hooks)

When to Use Each API

Component API - Quick integration, simple use cases, prefer components
Hook API - Need state management, composable logic, custom layouts
Advanced Hook API - Complete control, custom UI, complex interactions

Wrapping Up

react-cropper-2 brings CropperJS 2.x's modern web component architecture to React with three flexible APIs, full TypeScript support, and comprehensive testing.

Resources

Try it in your next React project and let me know what you think! Questions and feedback are always welcome.

DEV Community: Israel Merljak