react-advanced-cropper: a React image cropper you can restyle and rewire

A beta that wants a tilde, not a caret

The most important line in the README is a warning, and it changes how you should write your package.json. It is the beta version, the API can be changed in the future, and therefore it is recommended to fix the version with a tilde. That is a specific instruction rather than a general caution, because a caret range would pull in a breaking change on the next minor release while a tilde range only accepts patch updates. The library is presented as the advanced one that gives you the opportunity to create your own croppers suited for any website design, and the key phrase is that you are able to change not only the cropper appearance but customise its behaviour as well. The repository description says the same thing in slightly different words, that the library embraces the power of the advanced cropper core so you can create croppers exactly suited for your website design. The primary language is TypeScript, and the last push to the repository was on 2026-07-25.

Installing it is one command in either package manager

The install is the standard pair of commands, and the package name is the same in both:

npm install --save react-advanced-cropper

yarn add react-advanced-cropper

The package manifest records the distribution details that matter for bundlers. The main field points at a CommonJS build at dist/index.cjs.js, the module field at an ESM build for bundlers, and there is a separate unpkg and jsdelivr entry pointing at a global build, so a script tag can load the library without a bundler at all. Types are published as dist/index.d.ts. The engine requirements are deliberately loose, Node 8 or newer and npm 5 or newer, but the peer dependency is the constraint that matters for an application: React 16.8.0 or newer, which is the version that introduced hooks, and the component is written as a function component with useState.

The whole example is a component, a ref callback and three props

The getting started example is short because the component does most of the work. You import the component and the ref type, you import the stylesheet, you keep the image URL in state, and you render:

import React, { useState } from 'react';
import { CropperRef, Cropper } from 'react-advanced-cropper';
import 'react-advanced-cropper/dist/style.css'

export const GettingStartedExample = () => {
	const [image, setImage] = useState(
		'https://images.unsplash.com/photo-1599140849279-1014532882fe?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1300&q=80',
	);

	const onChange = (cropper: CropperRef) => {
		console.log(cropper.getCoordinates(), cropper.getCanvas());
	};

	return (
		<Cropper
			src={image}
			onChange={onChange}
			className={'cropper'}
		/>
	)
};

Two details are easy to miss. The stylesheet is a separate import, so a build that forgets it gets an unstyled cropper rather than an error. And the onChange callback receives the cropper ref, from which you call getCoordinates and getCanvas to read the current crop and the canvas element. The component does not hand you a cropped data URL; you ask it what you need.

The cropper needs a sized container, and the README says so

The stylesheet snippet that follows the example is not decoration. It carries a comment explaining that you may need to set the limits for the cropper sizes or its container sizes, otherwise a cropping image will try to fill all available space:

/*
  Maybe you need to set the limits for the cropper sizes or its container sizes
  otherwise a cropping image will try to fill all available space
*/
.cropper {
  height: 600px;
  background: #DDD;
}

The class name in the snippet is the same className passed to the component in the example, which is the join between the two halves of the API: the component names its root block and you style that block with CSS. A fixed height and a background colour are enough to get a workable cropper, and the comment is a warning that without them the image expands to fill whatever room it is given.

Three cropper types, and two ways of working with the image

The feature list names what the component supports out of the box: full mobile and desktop support, support for all three main types of croppers, support for both canvas and coordinates modes, minimum and maximum aspect ratios, custom size restrictions, and zoom, rotate and resize of the image, with auto-zoom and transitions. The prop table makes the configuration surface concrete. The stencil is a component you supply, with RectangleStencil as the default, and stencilProps passes options into it, which is how the shape of the crop area is customised. The cropper can also work in coordinates mode instead of canvas mode, with canvas defaulting to true, and the minimum and maximum width and height are given as percentages of the crop area, so the limits scale with the container rather than being pixel counts. The imageRestriction prop takes one of fillArea, fitArea, stencil or none, with fillArea as the default, and it is what decides how the image behaves when it does not match the shape of the stencil.

The wrapper and background are components too

The part that makes this library different from a fixed cropper is that the surrounding structure is replaceable as well. The wrapperComponent prop takes a component, defaulting to CropperWrapper, and wrapperProps passes options to it, so the frame around the crop area can be rebuilt. The background under the image works the same way, with backgroundWrapperComponent defaulting to CropperBackgroundWrapper and its own props. Alongside those there are the class name props for the root block, the image, the boundaries area and the background, which is what lets you restyle the cropper without replacing any components at all. That is the difference between a library that gives you a fixed rectangle with a colour scheme and one that lets you rebuild the whole interaction, and it is the reason the description talks about creating croppers exactly suited for your website design.

Defaults that decide how it behaves out of the box

A few defaults are worth reading before you accept them. The autoZoom prop is documented as enabling and disabling transitions with a default of true, and the transitions prop enables and disables auto zoom with a default of false, so the two are named in a way that is easy to misread. The checkOrientation prop defaults to true and controls whether EXIF orientation is checked, which matters for photographs taken on a phone, since without it an image with a rotation tag can be cropped on the wrong axis. The resizeImage, moveImage and rotateImage props take either a boolean or an options object, with resize and move defaulting to true and rotateImage defaulting to false. The defaultSize, defaultPosition and defaultTransforms props take an object or a function, which is how you set the initial state of the crop, and the function form matters because the initial values may depend on the image that has loaded.

A rollup build, jest tests and a documentation site in the repository

The repository is a TypeScript library with a rollup build, a jest test suite and a documentation site, and the scripts show the shape of it. The build runs a clean step, then a library build through rollup, then a themes build, and there is a start script that runs rollup in watch mode for development. The prepare hook runs the build, so the library is compiled when it is installed from a git reference. The tests run with jest, and the development dependencies include the rollup plugins for TypeScript, Babel, commonjs and node resolution, plus the react testing library and a Cypress based testing library. The example directory is a Docusaurus site, with its own config and sidebars, and the deploy script builds the example and pushes it to gh-pages, which is where the documentation and the live examples come from. The manifest version is 0.20.2, while the only tagged release listed for the project is 0.15.0 from 2022, which is another sign that this package moves quickly.

Editorial conclusion

react-advanced-cropper suits a product team that needs the cropper to match a bespoke design rather than a stock one, since the stencil and the wrapper are both replaceable components and the behaviour options are as configurable as the look. It does not suit a project that wants a stable API on a fixed version range, because the README calls the library a beta and says the API can change. Before adopting it, pin the version with a tilde range as the README advises, and check the peer dependency, since the component expects React 16.8 or newer for the hooks it uses.

Frequently asked questions

Official sources

1. advanced-cropper/react-advanced-cropper on GitHub
2. Issues
3. Project website
4. README
5. Releases