@bicycle-codes/image-cropper

Image Cropper

types module semantic versioning license

An HTML5 image cropping tool. Features a rectangular crop area. The crop area's aspect ratio can be enforced during dragging. The crop image can either be 1:1 or scaled to fit an area. Also supports multitouch on touch supported devices.

fork

This is a fork of AllanBishop/ImageCropper, just packaging and exporting ergonomically for npm consumption.

Thanks @AllanBishop for working in the world of open source.

Screenshot

Screenshot

Live demo

Live demo on JSBin

install

npm i -S @bicycle-codes/image-cropper

Add files

copy

Copy to a location accessible by your web server

cp ./node_modules/@bicycle-codes/image-cropper/dist/index.min.js ./public/image-cropper.js

Add the script to your application.

<script src="/image-cropper.js"></script>

bundle

This is ergonomic to use with a JS bundler such as vite. Just import:

import { ImageCropper } from '@bicycle-codes/image-cropper'

Or import a minified file:

import { ImageCropper } from '@bicycle-codes/image-cropper/min'

example

Given HTML like this

<canvas id="the-canvas" width="600" height="400">
    An alternative text describing what your canvas displays.
</canvas>

In your JS code,

import { ImageCropper } from '@bicycle-codes/image-cropper'

const width = 600
const height = 300
const canvas = document.getElementById('the-canvas')

const cropper = new ImageCropper(
    canvas,  // <-- HTML canvas element
    canvas.width / 2 - width / 2,  // <-- left postition of crop area
    canvas.height / 2 - height / 2,  // <-- top position of crop area
    width,  // <-- initial width of the crop area
    height,  // <-- initial height of the crop area
    true  // <-- Keep the aspect ratio to the given width and height
)

const img = document.getElementById('my-image')
cropper.setImage(img)

Public Functions

ImageCropper(canvas, x, y, width, height, keepAspect, touchRadius):void

Constructor function that initializes the image cropper.

Parameter Description
canvas The canvas element that the cropping tool will display on.
x Optional: The left position of the crop area.
y Optional: The top position of the crop area.
width Optional: The initial width of the crop area.
height Optional: The initial height of the crop area.
keepAspect Optional: Enforces that the aspect ratio is kept when dragging the crop area. The aspect ratio is defined by the width and height paramater.
touchRadius Optional: The radius for detecting touches/clicks on the corner drag markers and the centre drag marker.

getCroppedImage(fillWidth, fillHeight):Image

Returns an image that is cropped from the source image based on the crop area. If no fillWidth and fillHeight is set the image will be a 1:1 crop. If fillWidth and fillHeight are set the cropped image will scale to fit. It is recommended to ensure the fillWidth and fillHeight are set to the same aspect ratio as the crop area to prevent distortion.

Parameter Description
fillWidth Optional: The fill width that the cropped area will map to.
fillHeight Optional: The fill height that the cropped area will map to.

setImage(image)

Set the image for the image cropper.

Parameter Description
image The image that will be used for cropping.

isImageSet():boolean

Checks to see if an image has been set.

getCropBounds():Bounds

Returns the bounds (left, right, top, bottom) of the crop area relative to the original source image.

Example code

<!DOCTYPE html>
<html>
<head lang="en">
        <meta charset="UTF-8">
        <title>Image Cropper Test</title>
    </head>
    <body>
        <div>
            Select image to crop: <input type="file" id="fileInput" name="file" multiple="" />
        </div>
        <div>
            <canvas id="imageCanvas" width="600" height="400" style="border:0px solid #000000;">
            </canvas>
        </div>

        <div>
            Cropped image:
        </div>

        <div id="preview"></div>

        <script src="ImageCropperTest.js"></script>
        <script src="ImageCropper.js"></script>
    </body>
</html>

ImageCropperTest.js

let crop;
window.onload = function () {
    const canvas = document.getElementById("imageCanvas");
    const width = 600;
    const height = 300;

    crop = new ImageCropper(
        canvas,
        canvas.width / 2 - width / 2,
        canvas.height / 2 - height / 2,
        width,
        height,
        true
    );

    window.addEventListener('mouseup', preview);
};

function preview () {
    if (crop.isImageSet()) {
        const img = crop.getCroppedImage(400, 200);
        img.onload = (function () { return previewLoaded(img); });
    }
}

function previewLoaded (img) {
    if (img) {
        document.getElementById("preview").appendChild(img);
    }
}

function handleFileSelect (evt) {
    const file = evt.target.files[0];
    const reader = new FileReader();
    const img = new Image();

    //listener required for FireFox
    img.addEventListener("load", function () {
        crop.setImage(img);
        preview();
    }, false);

    reader.onload = function () {
        img.src = reader.result;
    };

    if (file) {
        reader.readAsDataURL(file);
    }
}

develop

Start a local server of the example directory:

npm start

License

MIT license. See the LICENSE file.

Settings

Member Visibility

Theme

On This Page

Image Cropper