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

import { Cropper } from 'react-avatar-crop';
import 'react-avatar-crop/css';

...
<Cropper
    file={sourceFile}
    onSave={blob => setTargetFile(blob)}
    saveButton={saveBtnRef}
    box={{
        width: '500px',
        height: '400px',
    }}
    wheelControl
    rangeControl
/>

Elaborate example

import { useState, useRef, useEffect } from 'react';
import { Cropper } from 'react-avatar-crop';
import 'react-avatar-crop/css';

const Example = () => {
    const [sourceFile, setSourceFile] = useState(null);
    const [targetFile, setTargetFile] = useState(null);
    const saveBtnRef = useRef(null);
    const targetImgRef = useRef(null);

    useEffect(() => {
        if (targetFile) {
            targetImgRef.current.src = URL.createObjectURL(targetFile);
        }
    }, [targetFile]);

    return (
        <div>
            <h3>Your avatar</h3>
            <input
                type="file"
                accept="image/*"
                name="avatar"
                onChange={evt => setSourceFile(evt.target.files[0])}
            />
            {Boolean(sourceFile) &&
                <>
                    <Cropper
                        file={sourceFile}
                        onSave={blob => setTargetFile(blob)}
                        saveButton={saveBtnRef}
                        box={{
                            width: '500px',
                            height: '400px',
                        }}
                        wheelControl
                        rangeControl 
                    />
                    <button ref={saveBtnRef}>Save</button>
                </>
            }
            <img
                ref={targetImgRef}
                style={{
                    borderRadius: '50%',
                    display: 'block',
                }}
            />
        </div>
    );
};

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 |