react-cropper-2

A modern React wrapper for CropperJS 2.x

A TypeScript-first React library that provides idiomatic React bindings for CropperJS 2.x web components.

Features

• ✅ CropperJS 2.x Support - Built for the latest CropperJS web components
• ✅ React 19 Compatible - Full support for React 19.x
• ✅ TypeScript First - Complete type safety with strict mode
• ✅ Three APIs - Component, simplified hook, and advanced hook
• ✅ Modern Architecture - Built on web standards
• ✅ Fully Tested - 96%+ test coverage with 55 passing tests
• ✅ Interactive Docs - Storybook documentation

Why react-cropper-2?

The original react-cropper library only supports CropperJS 1.x. CropperJS 2.x is a complete rewrite using modern web components, requiring new React bindings. This library provides three flexible APIs to work with CropperJS 2.x in React applications.

Installation

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

Quick Start

Using the Component (Recommended)

The simplest way to use the library:

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

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

  const handleGetBounds = () => {
    const bounds = cropperRef.current?.getBounds();
    console.log('Crop bounds:', bounds);
  };

  return (
    <div>
      <Cropper
        ref={cropperRef}
        src="/image.jpg"
        alt="Crop me"
        crossOrigin="anonymous"
        aspectRatio={16 / 9}
        onReady={() => console.log('Cropper ready!')}
        onChange={(e) => console.log('Crop changed:', e.detail.bounds)}
      />
      <button onClick={handleGetBounds}>Get Bounds</button>
      <button onClick={() => cropperRef.current?.reset()}>Reset</button>
    </div>
  );
}

Using the Hook

For more control and composition:

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

function App() {
  const { renderCropper, bounds, reset, clear, getCroppedCanvas } = useCropper({
    src: '/image.jpg',
    alt: 'Crop me',
    crossOrigin: 'anonymous',
    aspectRatio: 16 / 9,
    onReady: () => console.log('Ready!'),
    onChange: (e) => console.log('Changed:', e.detail),
  });

  const handleExport = async () => {
    const canvas = await getCroppedCanvas();
    const url = canvas?.toDataURL('image/png');
    // Use the cropped image
  };

  return (
    <div>
      {renderCropper({ style: { maxHeight: '500px' } })}
      <div>
        {bounds && <pre>{JSON.stringify(bounds, null, 2)}</pre>}
      </div>
      <button onClick={reset}>Reset</button>
      <button onClick={clear}>Clear</button>
      <button onClick={handleExport}>Export</button>
    </div>
  );
}

Advanced Usage

For maximum control, use the advanced hook:

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

function App() {
  const {
    canvasRef,
    selectionRef,
    bounds,
    isReady,
    getBounds,
    setBounds,
    reset,
    getCroppedCanvas,
  } = useCropperAdvanced({
    autoInitialize: true,
    onReady: (canvas) => console.log('Ready!', canvas),
    onChange: (e) => console.log('Changed:', e.detail),
  });

  return (
    <div>
      <cropper-canvas ref={canvasRef} background>
        <cropper-image
          src="/image.jpg"
          alt="Crop me"
          crossorigin="anonymous"
          rotatable
          scalable
          translatable
        />
        <cropper-selection
          ref={selectionRef}
          aspect-ratio={16 / 9}
          initial-coverage={0.8}
          movable
          resizable
          zoomable
          outlined
        >
          <cropper-grid role="grid" bordered covered />
          <cropper-crosshair centered />
          <cropper-handle action="move" theme-color="rgba(255, 255, 255, 0.35)" />
          <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>
      <button onClick={() => setBounds({ x: 50, y: 50, width: 200, height: 200 })}>
        Set Custom Bounds
      </button>
      <button onClick={reset}>Reset</button>
    </div>
  );
}

API Documentation

<Cropper> Component

Props

Prop	Type	Description
src	string	Image URL (required)
alt	string	Image alt text
crossOrigin	'anonymous' | 'use-credentials'	CORS setting
aspectRatio	number	Aspect ratio constraint (e.g., 16/9)
initialCoverage	number	Initial crop coverage (0-1)
background	boolean	Show background (default: true)
rotatable	boolean	Enable rotation (default: true)
scalable	boolean	Enable scaling (default: true)
translatable	boolean	Enable translation (default: true)
movable	boolean	Enable moving selection (default: true)
resizable	boolean	Enable resizing selection (default: true)
zoomable	boolean	Enable zooming (default: true)
outlined	boolean	Show selection outline (default: true)
onReady	(canvas: CropperCanvasElement) => void	Callback when ready
onChange	CropperEventHandler	Callback when crop changes
onCropStart	CropperEventHandler	Callback when crop starts
onCropMove	CropperEventHandler	Callback during crop movement
onCropEnd	CropperEventHandler	Callback when crop ends

Ref Methods

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

useCropper Hook

Simplified hook that handles rendering for you.

const {
  renderCropper,
  bounds,
  isReady,
  getBounds,
  setBounds,
  reset,
  clear,
  getCanvas,
  getSelection,
  getCroppedCanvas,
} = useCropper(options);

useCropperAdvanced Hook

Advanced hook for maximum control. You manage rendering yourself.

const {
  canvasRef,
  selectionRef,
  bounds,
  isReady,
  getBounds,
  setBounds,
  reset,
  clear,
  getCanvas,
  getSelection,
  getCroppedCanvas,
} = useCropperAdvanced(options);

Live Examples

Check out the interactive Storybook documentation with live examples for:

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

Development

# Install dependencies
npm install

# Start example app
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build library
npm run build

# Start Storybook
npm run storybook

# Build Storybook
npm run build-storybook

Project Structure

react-cropper-2/
├── src/
│   ├── components/
│   │   ├── Cropper.tsx              # Main component
│   │   └── Cropper.test.tsx         # Component tests
│   ├── hooks/
│   │   ├── useCropper.tsx           # Simplified hook
│   │   ├── useCropper.test.ts       # Hook tests
│   │   ├── useCropperAdvanced.ts    # Advanced hook
│   │   └── useCropperAdvanced.test.ts
│   ├── types/
│   │   ├── index.ts                 # TypeScript types
│   │   └── jsx.d.ts                 # JSX declarations
│   ├── stories/                     # Storybook stories
│   └── index.ts                     # Main export
├── examples/basic/                  # Example application
├── tests/setup.ts                   # Test configuration
└── dist/                            # Build output

Requirements

• React 18.0.0 or higher (works with React 19)
• CropperJS 2.0.1 or higher
• TypeScript 5.6+ (for TypeScript projects)

Browser Support

Supports all modern browsers that support:

• ES2020
• Web Components (Custom Elements)
• ES Modules

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT © 2025

Acknowledgments

• CropperJS - The underlying cropping library
• react-cropper - Inspiration from the v1 wrapper

Related Projects

• CropperJS - The underlying library (v2.x)
• react-cropper - React wrapper for CropperJS v1.x