mosch/react-avatar-editor

README

react-avatar-editor

Avatar / profile picture cropping component for React. Resize, crop and rotate your uploaded image using a simple and clean user interface.

Features

Fully typed, written in TypeScript
Works with React 17, 18, and 19
Resize, crop, and rotate
Rounded or square crop area
Built-in loading indicator
useAvatarEditor hook for easy access to the editor API
Zero runtime dependencies

Install

npm i react-avatar-editor

Usage

Basic

import AvatarEditor from 'react-avatar-editor'

function MyEditor() {
  return (
    <AvatarEditor
      image="https://example.com/photo.jpg"
      width={250}
      height={250}
      border={50}
      color={[255, 255, 255, 0.6]}
      scale={1.2}
      rotate={0}
    />
  )
}

With `useAvatarEditor` hook

The useAvatarEditor hook provides a clean API to access the editor's methods without managing refs manually. All methods return null if the editor isn't ready or no image is loaded.

import AvatarEditor, { useAvatarEditor } from 'react-avatar-editor'

function MyEditor() {
  const editor = useAvatarEditor()

  const handleSave = () => {
    const canvas = editor.getImageScaledToCanvas()
    if (canvas) {
      const dataUrl = canvas.toDataURL()
      // upload dataUrl to your server
    }
  }

  return (
    <div>
      <AvatarEditor
        ref={editor.ref}
        image="https://example.com/photo.jpg"
        width={250}
        height={250}
        border={50}
        scale={1.2}
      />
      <button onClick={handleSave}>Save</button>
    </div>
  )
}

Hook methods

Method	Returns	Description
`ref`	`RefObject`	Pass this to the `ref` prop of `AvatarEditor`.
`getImage()`	`HTMLCanvasElement \| null`	The cropped image at the original resolution.
`getImageScaledToCanvas()`	`HTMLCanvasElement \| null`	The cropped image scaled to the editor dimensions.
`getCroppingRect()`	`object \| null`	The crop area as `{ x, y, width, height }` (0–1 range).

With ref (alternative)

If you prefer using refs directly:

import { useRef } from 'react'
import AvatarEditor, { type AvatarEditorRef } from 'react-avatar-editor'

function MyEditor() {
  const editor = useRef<AvatarEditorRef>(null)

  return (
    <div>
      <AvatarEditor
        ref={editor}
        image="https://example.com/photo.jpg"
        width={250}
        height={250}
      />
      <button
        onClick={() => {
          const canvas = editor.current?.getImageScaledToCanvas()
        }}
      >
        Save
      </button>
    </div>
  )
}

Saving as JPEG (smaller files)

canvas.toDataURL() and canvas.toBlob() produce a PNG by default. PNG is lossless, so a cropped photo can end up several times larger than the JPEG you uploaded. Pass a type and quality to get a JPEG instead:

const canvas = editor.getImageScaledToCanvas()
canvas?.toBlob(
  (blob) => {
    if (!blob) return
    const formData = new FormData()
    formData.append('avatar', blob, 'avatar.jpg')
    fetch('/api/avatar', { method: 'POST', body: formData })
  },
  'image/jpeg',
  0.9, // quality, 0–1
)

Also pick the right method for your use case:

getImageScaledToCanvas() returns the crop at the editor's width × height. This is usually what you want for avatars.
getImage() returns the crop at the original image resolution. With a large camera photo that can be thousands of pixels wide, so the file will be large even as a JPEG.

JPEG has no transparency, so transparent areas (for example in an uploaded PNG) turn black. Set backgroundColor to fill them with a color, or keep PNG.

Responsive size

width and height also accept a percentage of the parent element. The editor measures its parent and follows it when it resizes. A percentage sets the size of the whole canvas, and the crop area is that minus border on each side.

<div style={{ width: '100%', maxWidth: 600 }}>
  <AvatarEditor image={image} width="100%" height={300} border={20} />
</div>

The canvas becomes display: block in this mode. A percentage height needs a parent with a fixed height, as in CSS. Resizing keeps the image, position and zoom. The crop area just changes size.

With drag and drop

Using react-dropzone:

import AvatarEditor from 'react-avatar-editor'
import Dropzone from 'react-dropzone'

function MyEditor() {
  const [image, setImage] = useState('https://example.com/photo.jpg')

  return (
    <Dropzone onDrop={([file]) => setImage(file)} noClick noKeyboard>
      {({ getRootProps, getInputProps }) => (
        <div {...getRootProps()}>
          <AvatarEditor width={250} height={250} image={image} />
          <input {...getInputProps()} />
        </div>
      )}
    </Dropzone>
  )
}

Animated rotation

The rotate prop can be animated using any animation library. Here's an example with motion:

import { useState } from 'react'
import { useMotionValue, useSpring, useMotionValueEvent } from 'motion/react'
import AvatarEditor from 'react-avatar-editor'

function MyEditor() {
  const [rotate, setRotate] = useState(0)
  const [animatedRotate, setAnimatedRotate] = useState(0)

  const rotateMotion = useMotionValue(0)
  const rotateSpring = useSpring(rotateMotion, { stiffness: 200, damping: 25 })

  useMotionValueEvent(rotateSpring, 'change', (v) => setAnimatedRotate(v))

  if (rotateMotion.get() !== rotate) {
    rotateMotion.set(rotate)
  }

  return (
    <>
      <AvatarEditor
        image="https://example.com/photo.jpg"
        rotate={animatedRotate}
      />
      <button onClick={() => setRotate((r) => r - 90)}>↺</button>
      <button onClick={() => setRotate((r) => r + 90)}>↻</button>
    </>
  )
}

Props

Prop	Type	Default	Description
`image`	`string \| File`		The URL or File object of the image to edit.
`width`	`number \| string`	`200`	Width of the crop area in pixels, or a percentage like `"100%"` (see Responsive size).
`height`	`number \| string`	`200`	Height of the crop area in pixels, or a percentage like `"50%"`.
`border`	`number \| number[]`	`25`	Border size around the crop area. Use an array `[horizontal, vertical]` for different values.
`borderRadius`	`number`	`0`	Border radius of the crop area. Set to `width / 2` for a circle.
`color`	`number[]`	`[0, 0, 0, 0.5]`	RGBA color of the crop mask overlay.
`borderColor`	`number[]`		RGBA color of the 1px border around the crop area. No border if omitted.
`backgroundColor`	`string`		Background color for transparent images (CSS color string).
`scale`	`number`	`1`	Zoom level. `1` = fit, `> 1` = zoom in, `< 1` = zoom out (requires `disableBoundaryChecks`).
`rotate`	`number`	`0`	Rotation in degrees.
`position`	`{ x, y }`		Center of the crop area (0–1 range). Set this + `onPositionChange` for controlled panning.
`style`	`CSSProperties`		Additional CSS styles for the canvas element.
`crossOrigin`	`string`		`crossOrigin` attribute for the image. Use `"anonymous"` for CORS images.
`showGrid`	`boolean`	`false`	Show a rule-of-thirds grid overlay.
`gridColor`	`string`	`"#666"`	Color of the grid lines.
`disableBoundaryChecks`	`boolean`	`false`	Allow the image to be moved outside the crop boundary.
`disableHiDPIScaling`	`boolean`	`false`	Disable `devicePixelRatio` scaling. Can improve performance on mobile.
`disableCanvasRotation`	`boolean`	`true`	When `false`, the canvas resizes to fit the rotated image.
`onLoadStart`	`() => void`		Called when image loading begins.
`onLoadSuccess`	`(image) => void`		Called when the image loads successfully.
`onLoadFailure`	`() => void`		Called when the image fails to load.
`onImageReady`	`() => void`		Called when the image is first painted on the canvas.
`onImageChange`	`() => void`		Called on every visual change (drag, scale, rotate, etc.).
`onMouseUp`	`() => void`		Called when the user releases the mouse after dragging.
`onMouseMove`	`(event) => void`		Called on every mouse/touch move while dragging.
`onPositionChange`	`(position) => void`		Called when the crop position changes. Receives `{ x, y }`.
`onRequestScaleChange`	`(scale) => void`		Called when the user zooms via +/- keys, pinch, or wheel. Receives the requested new scale.
`enableWheelZoom`	`boolean`	`false`	Zoom with the mouse wheel / trackpad. Requires `onRequestScaleChange`.
`keyboardStep`	`number`	`1`	Pixels to move per arrow key press. Shift multiplies by 10.

Contributing

pnpm install          # install dependencies
pnpm build            # build the library
pnpm lint             # run oxlint
pnpm fmt              # format with oxfmt
pnpm demo:dev         # run demo at localhost:3000

Kudos

Thanks to all contributors:

dan-lee, mtlewis, jakerichan, hu9o, ggwzrd, nmn, kukagg, benwiley4000, ruipserra, rdw, sktt, RKJuve, tibotiber, aumayr, yamafaktory, codedmart, chengyin, MahdiHadrich, jyash97, fivenp, pvcresin, shakaman, oyeanuj, dev-nima, kpbp, DedaDev, vitbokisch, pekq, MateusZitelli, kimon89, xaviergonz, jbrumwell, luisrudge, bytor99999, Mitelak, sahanDissanayake, sle-c, YacheLee, yogthesharma, taro-shono, tanguyantoine, lulzsun, mloeks, metacortex, exiify, thinhvoxuan, tvankith, yarikgenza, zhipenglin, TheMcMurder, notjosh, xulww, jimniels, jeffkole, deadlyicon, velezjose, lixiaoyan, brigand, florapdx, kuhelbeher, chris-rudmin, bluej100, dehbmarques, kimorq