react-avatar-crop

A lightweight, customizable, non-intrusive image cropper for using on the frontend. Its primary purpose is to enable end users to crop avatar/ profile images that they uploaded via input. With an intuitive design, it ensures a seamless and user-friendly experience. The package has no external dependencies and has a minimal footprint. It works seamlessly on both desktop and mobile devices, providing a consistent experience across platforms. Cropper requires the consuming project to have React installed.

Installation

npm install react-avatar-crop

Usage

Basic example

1import { Cropper } from 'react-avatar-crop';
2import 'react-avatar-crop/css';
3
4...
5<Cropper
6    file={sourceFile}
7    onSave={blob => setTargetFile(blob)}
8    saveButton={saveBtnRef}
9    box={{
10        width: '500px',
11        height: '400px',
12    }}
13    wheelControl
14    rangeControl
15/>

Elaborate example

1import { useState, useRef, useEffect } from 'react';
2import { Cropper } from 'react-avatar-crop';
3import 'react-avatar-crop/css';
4
5const Example = () => {
6    const [sourceFile, setSourceFile] = useState(null);
7    const [targetFile, setTargetFile] = useState(null);
8    const saveBtnRef = useRef(null);
9    const targetImgRef = useRef(null);
10
11    useEffect(() => {
12        if (targetFile) {
13            targetImgRef.current.src = URL.createObjectURL(targetFile);
14        }
15    }, [targetFile]);
16
17    return (
18        <div>
19            <h3>Your avatar</h3>
20            <input
21                type="file"
22                accept="image/*"
23                name="avatar"
24                onChange={evt => setSourceFile(evt.target.files[0])}
25            />
26            {Boolean(sourceFile) &&
27                <>
28                    <Cropper
29                        file={sourceFile}
30                        onSave={blob => setTargetFile(blob)}
31                        saveButton={saveBtnRef}
32                        box={{
33                            width: '500px',
34                            height: '400px',
35                        }}
36                        wheelControl
37                        rangeControl 
38                    />
39                    <button ref={saveBtnRef}>Save</button>
40                </>
41            }
42            <img
43                ref={targetImgRef}
44                style={{
45                    borderRadius: '50%',
46                    display: 'block',
47                }}
48            />
49        </div>
50    );
51};

API

Name	Type	Required	Default	Description
file	blob	yes		Input file selected by user
onSave	func	yes		Handles cropped image blob, e.g. uploads to a server
saveButton	ref	yes		Ref to a button, onSave will be attached to it
box	object	yes		Cropper element width and height
shape	object		{ borderRadius: '50%' }	Crop area width, height and border-radius
layer	object		{ dim: '40%', dimTransition: '1.5s' }	Layer around crop area
rangeControl	bool | object		{ color: 'grey' }	Range widget
wheelControl	bool | object		{ sensitivity: 5 }	Allows mouse wheel and trackpad zoom
pinchZoom	object		{ sensitivity: 3 }	Allows touch screen devices pinch zoom
buttonsControl	object		{ step: 3 }	Refs to zoomInControl, zoomOutControl and step size (1 to 10)
targetImage	object		{ type: 'image/png', quality: 1, preserveOriginalScale: false }	Config for target image