Cropt Readme

Cropt is a modern, lightweight image cropper with zero dependencies.

Is Cropt For Me?

Cropt is a clean ES6 class with clearly structured methods, perfect for cropping avatars, thumbnails, or any user-uploaded images. It uses a powerful resizing algorithm to prevent artifacts when shrinking large images, and works seamlessly on mobile and desktop.

Key Features: viewport resizing, rotation, pinch/scroll zoom, keyboard navigation, and export to Canvas or Blob — all in under 6KB gzip + minified.

Installing

Install Cropt as a package, or our Github repo.

NPM 
npm install cropt2
YARN 
yarn add cropt2
RECAP: BASIC USAGE 
import Cropt from 'cropt2';

const container = document.getElementById('demo');
const cropt = new Cropt(container);
cropt.bind('image.jpg');

Crop Container

Cropt will fit into the container you place it in. If your container has no height by default, nothing will appear, so please make sure you specify a minimum height for your container.

Options

Pass these as the second argument to the Cropt constructor.

Option Type Default Description
mouseWheelZoom "off" | "on" | "ctrl" "on" Control zoom via mouse wheel. Use "ctrl" to require Ctrl key.
viewport { width, height, borderRadius } { width: 220, height: 220, borderRadius: "0px" } Size and shape of crop area. Use borderRadius: "50%" for circle.
zoomerInputClass string "cr-slider" Custom class for the zoom slider (e.g., Bootstrap’s "form-range").
enableZoomSlider boolean true Show/hide the zoom slider.
enableKeypress boolean true Enable arrow keys to move image (ignored in input fields).
resizeBars boolean false Show resize handles to adjust viewport size.
enableRotateBtns boolean false Show rotation buttons (↺/↻) in toolbar.

Methods

Methods available on a Cropt instance.

Loads an image from URL. Optionally pass an initial zoom level (number) or a full preset object to restore a previous state.

cropt.bind('image.jpg', 1.2); // zoom to 1.2x
// OR
cropt.bind('image.jpg', {
  transform: { x: 10, y: 20, scale: 1.5, rotate: 90 },
  viewport: { width: 250, height: 250, borderRadius: '8px' }
});

→ Resolves when image is loaded and UI is ready.

Cleans up the instance and removes all DOM elements.

cropt.destroy();

→ No return value. Safe to call multiple times.

Recalculates layout. Call this if Cropt was hidden during initialization (e.g., in a modal).

// After modal opens
modal.addEventListener('shown.bs.modal', () => {
  cropt.refresh();
});

→ No return value.

Returns a canvas of the cropped image. If size is provided, the longest side is scaled to that value.

const canvas = await cropt.toCanvas(500);
document.body.appendChild(canvas);

→ Returns Promise<HTMLCanvasElement>.

Exports cropped image as Blob. Supports image/webp, image/jpeg, etc. Falls back to JPEG if WebP is unsupported with quality < 1.

const blob = await cropt.toBlob(800, 'image/jpeg', 0.8);
const url = URL.createObjectURL(blob);
img.src = url;

→ Returns Promise<Blob> with width and height properties.

Returns current crop state. Use for saving/restoring sessions or server-side cropping.

const data = cropt.get();
console.log(data.crop);      // { x, y, width, height }
console.log(data.transform); // { x, y, scale, rotate, origin }
console.log(data.viewport);  // { width, height, borderRadius }

→ Returns plain object with crop coordinates, transform, and viewport info.

Update options dynamically (e.g., change viewport size or enable rotation).

cropt.setOptions({
  viewport: { width: 300, height: 300, borderRadius: '50%' },
  enableRotateBtns: true
});

→ No return value. Re-renders UI if needed.

Programatically set zoom level (0–1 range, clamped to Cropt’s min/max).

cropt.setZoom(0.8);

→ No return value.

Rotate image by 0, 90, 180, or 270 degrees.

await cropt.setRotation(90);

→ Returns Promise<void> (waits for image rotation to complete).