Awesome

react-easy-crop

A React component to crop images/videos with easy interactions

Demo

Check out the examples:

• Basic example with hooks
• Basic example with class
• Basic example in Typescript
• Example with output of the cropped image
• Example with live output
• Example with server-side cropping using sharp
• Example with image selected by the user (+ auto-rotation for phone pictures)
• Example with round crop area and no grid
• Example without restricted position
• Example with crop saved/loaded to/from local storage
• Example with a video
• Example within scrollable content

Features

• Supports drag, zoom and rotate interactions
• Provides crop dimensions as pixels and percentages
• Supports any images format (JPEG, PNG, even GIF) as url or base 64 string
• Supports any videos format supported in HTML5
• Mobile friendly

If react-easy-crop doesn't cover your needs we recommend taking a look at Pintura

Pintura features cropping, rotating, flipping, filtering, annotating, and lots of additional functionality to cover all your image and video editing needs on both mobile and desktop devices.

Learn more about Pintura

Video tutorials from the community

• Create an image gallery with live cropping By Coding With Adam
• Crop an avatar and download the result By Manish Boro

Installation

yarn add react-easy-crop

or

npm install react-easy-crop --save

Basic usage

The Cropper is styled with position: absolute to take the full space of its parent. Thus, you need to wrap it with an element that uses position: relative or the Cropper will fill the whole page.

import { useState, useCallback } from 'react'
import Cropper from 'react-easy-crop'

const Demo = () => {
  const [crop, setCrop] = useState({ x: 0, y: 0 })
  const [zoom, setZoom] = useState(1)

  const onCropComplete = (croppedArea, croppedAreaPixels) => {
    console.log(croppedArea, croppedAreaPixels)
  }

  return (
    <Cropper
      image={yourImage}
      crop={crop}
      zoom={zoom}
      aspect={4 / 3}
      onCropChange={setCrop}
      onCropComplete={onCropComplete}
      onZoomChange={setZoom}
    />
  )
}

Styles

This component requires some styles to be available in the document. By default, you don't need to do anything, the component will automatically inject the required styles in the document head. If you want to disable this behaviour and manually inject the CSS, you can set the disableAutomaticStylesInjection prop to true and use the file available in the package: react-easy-crop/react-easy-crop.css.

Known issues

The cropper size isn't correct when displayed in a modal

If you are using the Cropper inside a modal, you should ensure that there is no opening animation that is changing the modal dimensions (scaling effect). Fading or sliding animations are fine. See #428, #409, #267 or #400 for more details.

Props

<a name="onCropCompleteProp"></a>

onCropComplete(croppedArea, croppedAreaPixels)

This callback is the one you should use to save the cropped area of the media. It's passed 2 arguments:

1. croppedArea: coordinates and dimensions of the cropped area in percentage of the media dimension
2. croppedAreaPixels: coordinates and dimensions of the cropped area in pixels.

Both arguments have the following shape:

const area = {
  x: number, // x/y are the coordinates of the top/left corner of the cropped area
  y: number,
  width: number, // width of the cropped area
  height: number, // height of the cropped area
}

<a name="onCropAreaChangeProp"></a>

onCropAreaChange(croppedArea, croppedAreaPixels)

This is the exact same callback as onCropComplete, but is triggered for all user interactions. It can be used if you are not performing any render action on it.

1. croppedArea: coordinates and dimensions of the cropped area in percentage of the media dimension
2. croppedAreaPixels: coordinates and dimensions of the cropped area in pixels.

Both arguments have the following shape:

const area = {
  x: number, // x/y are the coordinates of the top/left corner of the cropped area
  y: number,
  width: number, // width of the cropped area
  height: number, // height of the cropped area
}

onMediaLoaded(mediaSize)

Called when media gets successfully loaded. This is useful if you want to have a custom zoom/crop strategy based on media size.

Example:

const CONTAINER_HEIGHT = 300

const CroppedImage = ({ image }) => {
  const [crop, onCropChange] = React.useState({ x: 0, y: 0 })
  const [zoom, onZoomChange] = React.useState(1)
  return (
    <Cropper
      image={image}
      crop={crop}
      zoom={zoom}
      onCropChange={onCropChange}
      onZoomChange={onZoomChange}
      onMediaLoaded={(mediaSize) => {
        // Adapt zoom based on media size to fit max height
        onZoomChange(CONTAINER_HEIGHT / mediaSize.naturalHeight)
      }}
    />
  )
}

getInitialCropFromCroppedAreaPercentages(croppedAreaPercentages: Area, mediaSize: MediaSize, rotation: number, cropSize: Size, minZoom: number, maxZoom: number)

[Advanced Usage]

Used to calculate values for crop and zoom based on a desired croppedAreaPercentages value. See this CodeSandbox instance for a simple example.

getInitialCropFromCroppedAreaPixels(croppedAreaPixels: Area, mediaSize: MediaSize, rotation: number, cropSize: Size, minZoom: number, maxZoom: number)

[Advanced Usage]

See getInitialCropFromCroppedAreaPercentages.

Development

yarn
yarn start

Now, open http://localhost:3001/index.html and start hacking!

License

MIT

Maintainers

This project is maintained by Valentin Hervieu.

This project was originally part of @ricardo-ch organisation because I (Valentin) was working at Ricardo. After leaving this company, they gracefully accepted to transfer the project to me. ❤️

Contributors

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!