ImageCropper
Interactive image crop, zoom, rotate and flip with canvas export
Source
Package
Usage
ImageCropper lets users pan, zoom, rotate and flip an image behind a fixed crop window.
Drag the image to pan and use the mouse wheel to zoom:
Interactions
- Pan – drag the image or focus the viewport and use the arrow keys
- Zoom – pinch with two fingers, scroll the mouse wheel or use the zoom slider.
Press
+or-to zoom when the viewport is focused. SetminZoomandmaxZoomto limit zoom. - Rotate and flip – use the default controls or the controller actions
Set withControls to display the zoom slider and rotate, flip and reset buttons
under the viewport.
Aspect ratio
Set aspectRatio to control the shape of the crop window, for example 1 for a square or
16 / 9 for a widescreen crop. When aspectRatio is not set, the crop window matches the viewport
aspect ratio:
Circle crop
Set cropShape="circle" to display a circular crop window, for example for avatars.
The crop is always square and the exported image has a circular mask:
useImageCropper hook
ImageCropper supports the controller pattern with the useImageCropper hook.
When you pass a controller, set zoom, rotation, flip, crop shape and aspect ratio on the hook:
Example of using useImageCropper hook:
zoom: 1.0×, rotation: 0°, flipped: false
Controlled state
Zoom, rotation and flip can be controlled or uncontrolled with value, defaultValue and
onChange style props, both on ImageCropper and in useImageCropper:
The pan position cannot be controlled with props, set it with the controller setCrop action.
Exporting the crop
getCroppedImage returns a promise that resolves with the cropped image as a Blob or a data URL.
Use type, quality and output options to change the result format:
Preview
To export a remote image, set crossOrigin="anonymous" on ImageCropper and make sure the
image host sends permissive CORS headers, otherwise the promise is rejected. Object URLs and
data URLs, for example from a file input, do not need extra configuration.
With cropShape="circle", the area outside the circle is transparent. Use image/png or
image/webp type, with image/jpeg the corners are filled with an opaque color.
Server-side cropping
If you crop the image on the server, use getCropData() or the onCropChange callback instead
of exporting the image on the client. Both provide the crop rectangle in pixels of the source image
as { x, y, width, height, rotation }, onCropChange also receives it in percentages:
The rectangle is measured in the rotated image. Flip is not part of the crop data, get it from
controller.flip or onFlipChange. To reproduce the crop on the server:
- Apply the flip to the source image.
- Rotate the flipped image by
pixels.rotationdegrees, expanding the canvas to the rotated bounding box. - Extract the
pixelsrectangle from the result.
Custom layout
Use ImageCropper.Viewport, ImageCropper.Image and ImageCropper.Controls compound
components to change the layout, for example to render the controls above the viewport.
Pass children to ImageCropper.Controls to replace the default controls:
Disabled state
Set disabled to make the cropper non-interactive, for example to display a preview
of a saved crop. The default controls are disabled as well:
Pairing with Dropzone
Use Dropzone to pick an image, then pass its object URL to ImageCropper:
Drop an image here or click to select one
Accessibility
Set aria-label on ImageCropper.Viewport to describe what the user is cropping.
To localize the controls, render buttons with translated labels:
