Cropt v2 - lightweight JavaScript image cropper

Github

Originally based on Foliotek/Croppie, but rewritten as a modern ES module with a simpler API, higher quality image scaling, and numerous other improvements by Devtheorem.

It was extensively enhanced (but backwards compatible with v1) to include adjustable viewport, rotation, keyboard handling, and various optimizations and bug fixes. And packed to work as browser install, commonJS, esm package, etc.

Quick Start

• Look at the /docs directory for examples.
• Try our codepen.

Installation

npm install cropt2

Running Demo

npm run build
npm start

Usage

1. Include the cropt.min.css stylesheet on your page.
2. Add a div element to your HTML to hold the Cropt instance.
3. Import Cropt and bind it to an image:

import Cropt from "cropt2";

const presets = {};
const cropt = new Cropt(document.getElementById('demo'), presets);
cropt.bind("path/to/image.jpg");

Sizing

The Cropt boundary requires a minimum height of 100px but otherwise it will adjust to the size of the container it is in. If toolbar (rotate, zoom) features, it builds a 32px high toolbar at the bottom.

Options

viewport

Type: { width: number, height: number, borderRadius: string }
Default value: { width: [container]-60px, height: [container]-60px, borderRadius: "0px" }

Defines the size and shape of the crop box. For a circle shape, set the border radius to "50%".

enableZoomSlider

Type: boolean Default value: true

Toggle if hiding the zoom slider.

enableKeypress

Type: boolean Default value: true

Toggle if allow listening for keyboard arrow keys for moving image. Will ignore if active element is a user input one (input box, text area, button).

resizeBars

Type: boolean Default value: false

Optionally to show resize handles (grab-bars) to adjust the viewport width/height.

enableRotateBtns

Type: boolean Default value: false

Toggle if showing rotation buttons beside the zoom slider bar. If both are off (enableZoomSlider and this), the toolbar is hidden.

mouseWheelZoom

Type: "off" | "on" | "ctrl"
Default value: "on"

If set to "off", the mouse wheel cannot be used to zoom in and out of the image. If set to "ctrl", the mouse wheel will only zoom in and out while the CTRL key is pressed.

zoomerInputClass

Type: string
Default value: "cr-slider"

Optionally set a different class on the zoom range input to customize styling (e.g. set to "form-range" when using Bootstrap).

Methods

bind(src: string, preset: number | { transform, viewport }): Promise<void>

Takes an image URL as the first argument, and an optional initial zoom value OR preset restore data for image placement in viewport. Returns a Promise which resolves when the image has been loaded and state is initialized.

destroy(): void

Deconstructs a Cropt instance and removes the elements from the DOM.

refresh(): void

Recalculate points for the image. Necessary if the instance was initially bound to a hidden element.

toCanvas(size: number | null = null): Promise<HTMLCanvasElement>

Returns a Promise resolving to an HTMLCanvasElement object for the cropped image. If size is specified, the cropped image will be scaled with its longest side set to this value.

toBlob(size: number | null = null, type = "image/webp", quality = 1): Promise<Blob>

Returns a Promise resolving to a Blob object for the cropped image. If size is specified, the cropped image will be scaled with its longest side set to this value. The type and quality parameters are passed directly to the corresponding HTMLCanvasElement.toBlob() method parameters.

get(): { crop: { left, top, right, bottom }, transform: { x, y, scale, rotate, origin: {x, y}}, viewport: { width, height, borderRadius } }

Returns information about the current crop state (all numbers):

• crop: Crop coordinates on the original image (left, top, right, bottom in pixels). (Note: if rotation present, image must be rotated FIRST then crop coordinates will apply)
• transform: Information for re-placement of image within viewport
• viewport: Final viewport dimensions and styling (width, height, borderRadius)

Useful for server-side cropping or saving user selections.

setOptions(options: CroptOptions): void

Allows options to be dynamically changed on an existing Cropt instance.

setZoom(value: number): void

Set the zoom of a Cropt instance. The value must be between 0 and 1, and is restricted to the min/max set by Cropt.

setRotation(value: number): void

Set a rotation factor (0, 90, 180, 270) to the image.

Visibility and binding

Cropt is dependent on its container being visible when the bind method is called. This can be an issue when your component is inside a modal or block that isn't shown (ex. style = display:none).

If you have issues getting the correct result, and your Cropt instance is shown inside a modal, try taking it out of the modal and see if the issue persists. If not, make sure that your bind method is called after the modal finishes opening.

If a Cropt instance needs to be hidden and then re-shown, call the refresh() method to recalculate properties for the displayed image.

Browser support

Cropt is tested in the following browsers:

• Firefox
• Safari
• Chrome
• Edge
• Mobile Safari

Cropt should also work in any other modern browser using an engine based on Gecko, WebKit, or Chromium.

License

MIT