react-image-crop

react-image-crop is a lightweight React component that renders an interactive, draggable crop overlay over an image (or any element), with no runtime dependencies and a footprint under 5KB gzipped. It supports both free-form and fixed-aspect-ratio crops, works with pixel or percentage-based coordinates for responsive layouts, and is fully touch- and keyboard-accessible.

Rather than performing any actual image manipulation itself, the component’s job is purely to manage crop selection state — reporting the current crop rectangle back to the consumer via callbacks — leaving pixel extraction (e.g. via a <canvas>) to the caller. This narrow scope keeps the library small and framework-idiomatic, and it works with any React-renderable content, not just <img> elements.

What You Get

• A ReactCrop component supporting free-form or fixed-aspect-ratio crop selection
• Support for both pixel-based (PixelCrop) and percentage-based (PercentCrop) crop coordinates for responsive layouts
• Full touch and keyboard accessibility (arrow-key nudging, ARIA labels) out of the box
• Min/max crop size constraints and circular crop-area rendering
• A tiny footprint (under 5KB gzipped) with zero runtime dependencies
• TypeScript type definitions shipped directly from source (types.ts)

Common Use Cases

• Avatar/profile photo upload flows where users crop their photo before saving
• Building a custom image editor UI that needs a crop-selection rectangle over a canvas or image
• Cropping non-image React content (e.g. a video frame or arbitrary DOM element) using the same drag-select interaction
• Generating a client-side cropped preview by combining the reported crop rectangle with a <canvas> draw call
• Responsive crop UIs that need percentage-based crop coordinates across different viewport sizes

Under The Hood

Architecture — The entire library is a single class component (src/ReactCrop.tsx, ~850 lines) that manages pointer/touch event handling directly via refs and document-level event listeners (DOC_MOVE_OPTS), computing crop-rectangle geometry (resize handles, aspect-ratio containment, clamping) through pure helper functions in src/utils.ts (clamp, containCrop, convertToPercentCrop, convertToPixelCrop, nudgeCrop). src/types.ts defines the Crop/PixelCrop/PercentCrop/Ords types shared across the component and utils.

Tech Stack — Written entirely in TypeScript with React as the only peer dependency (no runtime dependencies at all), styled via a single ReactCrop.scss file, and built with Vite (vite.config.ts) to emit both ESM and UMD bundles plus a bundled CSS file, distributed via npm, bun.lock, and pnpm-lock.yaml are present for the dev workflow.

Code Quality — There is no automated test suite in the repository (no test/*.test.* files found); quality control instead relies on ESLint (eslint src --ext ts,tsx --max-warnings 0) and manual verification through the bundled demo app (src/demo/) and CodeSandbox examples linked from the README. This is a real gap in this otherwise well-scoped component.

API Design — The public API is a single <ReactCrop crop={...} onChange={...} onComplete={...}> component with a compact, well-documented prop surface (aspect, disabled, locked, circularCrop, min/max sizes, custom ARIA labels) and extensive inline JSDoc comments on every prop, making it quick to integrate; the trade-off for its small footprint is that consumers must write their own canvas-drawing code to actually extract the cropped pixels, which the README’s FAQ section walks through explicitly.