v1.2.0 — Image Cropping with CropView

Release Date: April 8, 2026

This release introduces the CropView component — a WhatsApp-style image cropper that pairs seamlessly with the Camera component. As always, the release is fully backward compatible with zero breaking changes.

---

🎯 Highlights

New CropView Component

A standalone, fully interactive image cropping component designed for the take photo → crop → confirm workflow:

import { Camera, CropView, CameraRef, CropViewRef } from 'react-webcam-pro';

const App = () => {
  const cameraRef = useRef<CameraRef>(null);
  const cropRef = useRef<CropViewRef>(null);
  const [photo, setPhoto] = useState<string | null>(null);
  const [showCrop, setShowCrop] = useState(false);

  const handleTakePhoto = () => {
    const img = cameraRef.current?.takePhoto();
    if (img) {
      setPhoto(img as string);
      setShowCrop(true);
    }
  };

  return (
    <>
      {showCrop && photo ? (
        <CropView
          ref={cropRef}
          image={photo}
          cropAspectRatio={1}
          cropShape="rect"
          onCropComplete={(result) => {
            setPhoto(result.base64);
            setShowCrop(false);
          }}
          onCropCancel={() => setShowCrop(false)}
        />
      ) : (
        <Camera ref={cameraRef} />
      )}
      <button onClick={handleTakePhoto}>📸 Take Photo</button>
    </>
  );
};

Key Features

• Cross-platform interactions — Built on the Pointer Events API, works with mouse, touch, and pen input.
• Drag & resize — Move the crop box by dragging the center; resize via corner and edge handles.
• Aspect ratio lock — Optionally lock the crop box to any aspect ratio (1:1, 16:9, 4:3, etc.).
• Circle crop — Visual circular crop overlay for profile pictures and avatars.
• Built-in toolbar — Confirm (✓), Cancel (✕), and Reset (↺) buttons with customizable labels.
• Rule-of-thirds grid — Visual grid lines inside the crop box for better composition.
• SVG mask overlay — Semi-transparent overlay outside the crop area for clear visual feedback.
• Imperative API — Control via ref: cropImage(), resetCrop(), getCropArea().
• Canvas-based extraction — Uses the Canvas API for pixel-perfect cropped output in base64 and ImageData formats.
• Fully responsive — Automatically adapts to container size changes.
• Zero dependencies — No additional packages required beyond the existing peer deps.

---

📦 New Exports

Export	Kind	Description
CropView	Component	Image cropping component
CropViewProps	Type	Props interface for CropView
CropViewRef	Type	Ref interface for CropView (imperative methods)
CropArea	Type	Fractional crop coordinates { x, y, width, height }
CropResult	Type	Crop output { base64, imageData, cropArea }

---

🎮 CropView Props

Prop	Type	Default	Description
image	string	—	Source image (base64 data URL). Required.
cropAspectRatio	number	undefined	Lock crop to aspect ratio (width / height)
cropShape	'rect' | 'circle'	'rect'	Visual shape of crop area
minCropSize	number	0.1	Minimum crop size (0–1 fraction)
onCropComplete	(result: CropResult) => void	undefined	Confirm button callback
onCropCancel	() => void	undefined	Cancel button callback
labels	{ confirm?, cancel?, reset? }	{ '✓', '✕', '↺' }	Toolbar button labels
className	string	undefined	CSS class name
style	CSSProperties	undefined	Inline styles

🎛️ CropView Methods (via Ref)

Method	Returns	Description
cropImage()	Promise<CropResult>	Extracts the cropped image
resetCrop()	void	Resets crop to initial state
getCropArea()	CropArea	Returns current crop coordinates

---

📁 New Files

File	Purpose
src/components/CropView/CropView.tsx	Main component
src/components/CropView/CropView.types.ts	TypeScript interfaces
src/components/CropView/CropView.styles.ts	styled-components
src/components/CropView/cropUtils.ts	Pure geometry & canvas utilities
src/components/CropView/useCropInteraction.ts	Pointer events hook
test/cropUtils.test.ts	Unit tests for utilities
test/CropView.test.tsx	Component tests

---

🧪 Tests

• 67 new tests covering:
  • All pure geometry functions in cropUtils (clamp, move, resize, initial area, extract)
  • CropView rendering, props, callbacks, labels, cropShape
  • Imperative ref methods: cropImage(), resetCrop(), getCropArea()
  • Aspect ratio enforcement during resize
  • Backward compatibility — Camera and CropView coexistence
• 136+ total tests across 4 test suites, all passing.

---

🔄 Migration from v1.1.0

Zero breaking changes. Just update:

npm install react-webcam-pro@latest

All existing code continues to work exactly as before. The CropView component is entirely additive — it doesn't affect the Camera component in any way.

---

📚 Documentation

• Cropping Guide — Complete guide with examples and best practices.
• CropView Props — Full props reference.
• CropView Methods — Imperative methods reference.
• CropView Types — TypeScript type definitions.

---

Installation

npm install react-webcam-pro

yarn add react-webcam-pro

pnpm add react-webcam-pro