ImageCropper - crop an image in the browser

Loaded on demand — part of the feature bundle now.imagecrop.min.js (+ .css), not of now.core.min.js: a file field with data-crop="true" loads it; code that uses ImageCropper directly calls await Now.require('ImageCropper') first — see Feature bundles

ImageCropper opens one image in a crop dialog, lets the user move, zoom and turn it under a frame, and returns the result as a new File.
The frame stays fixed at the requested aspect ratio and the image moves beneath it, always covering the whole frame, so the result never has empty edges.

The usual way in is FileElementFactory, opened by data-crop="true" on a file field.
This page covers the cropper itself, for calling it from code.

Table of Contents

1. Usage
2. Options
3. Controls in the crop dialog
4. The resulting file
5. Cropping again from the original
6. CSS

Usage

await Now.require('ImageCropper');

const file = await ImageCropper.open(input.files[0], {aspect: '3/4', width: 600});
if (file) {
  // the cropped File
} else {
  // the user pressed Cancel, the close button or Escape
}

ImageCropper.open(source, options)

Returns Promise<File|null> — null when the user cancels.
Rejects with an Error (translated message "Unable to open this image") when the image cannot be opened: not an image, or a type the browser cannot read.

One crop dialog is shown at a time. open() calls may overlap; the next image waits until the previous dialog has closed.

Options

Every option takes a number or the string a data attribute carries.

Controls in the crop dialog

Wheel and pinch zoom keep the point under the pointer in place · Escape closes the crop dialog only, not a modal open beneath it.
The crop area refits its frame whenever it changes size (turning a phone or resizing the window keeps the selection).

The resulting file

• width × round(width / aspect) px (or the cropped area's own size when width is 0)
• The source's own name while the type is unchanged · a new type changes the extension (photo.png + format: 'jpeg' = photo.jpg)
• A source without a name (Blob, data: URL) is called image + extension
• Browsers that cannot write WebP (Safari) produce JPEG instead
• JPEG has no transparency: transparent parts of the source become white
• A camera photo's orientation (EXIF) is already applied when the image opens

Cropping in the browser is not a security boundary: the server must still check the file type and save the image anew
(Kotchasan's UploadedFile::cropImage() / resizeImage(), for example).

Cropping again from the original

A File ImageCropper produced remembers its source and how it was cropped.
Passing that File to open() again opens the original at the same position, zoom and turn, so the image is not resampled each time it is edited.

let photo = await ImageCropper.open(original, {aspect: 1, width: 400});
// later: edit the crop
photo = await ImageCropper.open(photo, {aspect: 1, width: 400}) || photo;

CSS

File Now/css/image-cropper.css (in now.imagecrop.min.css)