react-image-crop

A dependency-free, accessible React component for interactive image and element cropping.

Library
npm
v11.1.2
4,108 stars
ISC

Repository Health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum. How we score it →
54 /100 Fair
Development Activity 8
Maintenance 44
Community 64
Maturity 60
Momentum 40

Technical Analysis

AI-assessed by reading the actual repository — architecture, code quality, innovation, and documentation. How we score it →
74 /100 Good
Architecture 78
Code Quality 62
Innovation 72
Learning Curve 85

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.

Join founders buildingwith open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on Substack
Join 750+ subscribers