CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-cropperjs

JavaScript image cropper with extensive cropping capabilities and web component support.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

CropperJS

CropperJS is a comprehensive JavaScript image cropping library that provides extensive image manipulation capabilities including move, zoom, rotate, and scale operations with precise control over image dimensions and aspect ratios. It offers both a JavaScript API and a web component-based approach with zero external dependencies and cross-browser compatibility.

Package Information

  • Package Name: cropperjs
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install cropperjs

Core Imports

import Cropper from 'cropperjs';

For CommonJS:

const Cropper = require('cropperjs');

For utility functions and components:

import { isString, CROPPER_CANVAS, CropperImage } from 'cropperjs';

Basic Usage

import Cropper from 'cropperjs';

// Create a cropper instance from an image element
const image = document.querySelector('#image');
const cropper = new Cropper(image, {
  container: document.querySelector('#container'),
  template: '<cropper-canvas><cropper-image></cropper-image></cropper-canvas>'
});

// Get cropper elements
const canvas = cropper.getCropperCanvas();
const cropperImage = cropper.getCropperImage();
const selection = cropper.getCropperSelection();

Architecture

CropperJS is built around several key components:

  • JavaScript API: Main Cropper class for programmatic control and integration
  • Web Components: Custom HTML elements (<cropper-canvas>, <cropper-image>, etc.) for declarative usage
  • Utility Library: Type checking functions, event handling, and mathematical operations
  • Transform System: Matrix-based transformations for precise image manipulation
  • Event System: Custom events for interaction handling and state changes

Capabilities

JavaScript API

Core JavaScript interface for creating and managing cropper instances. Provides programmatic access to all cropping functionality.

class Cropper {
  static version: string;
  element: HTMLImageElement | HTMLCanvasElement;
  options: CropperOptions;
  container: Element;
  
  constructor(
    element: HTMLImageElement | HTMLCanvasElement | string,
    options?: CropperOptions
  );
  
  getCropperCanvas(): CropperCanvas | null;
  getCropperImage(): CropperImage | null;
  getCropperSelection(): CropperSelection | null;
  getCropperSelections(): NodeListOf<CropperSelection> | null;
}

interface CropperOptions {
  container?: Element | string;
  template?: string;
}

JavaScript API

Canvas Operations

Interactive canvas container that handles user interactions including touch, mouse, and wheel events for cropping operations.

class CropperCanvas extends CropperElement {
  background: boolean;
  disabled: boolean;
  scaleStep: number;
  themeColor: string;
  
  $setAction(action: string): this;
  $toCanvas(options?: CanvasOptions): Promise<HTMLCanvasElement>;
}

interface CanvasOptions {
  width?: number;
  height?: number;
  beforeDraw?: (context: CanvasRenderingContext2D, canvas: HTMLCanvasElement) => void;
}

Canvas Operations

Image Manipulation

Advanced image transformation capabilities including rotation, scaling, translation, and matrix-based transformations.

class CropperImage extends CropperElement {
  rotatable: boolean;
  scalable: boolean;
  skewable: boolean;
  translatable: boolean;
  initialCenterSize: string;
  
  $ready(callback?: (image: HTMLImageElement) => unknown): Promise<HTMLImageElement>;
  $move(x: number, y?: number): this;
  $rotate(angle: number | string, x?: number, y?: number): this;
  $zoom(scale: number, x?: number, y?: number): this;
  $transform(a: number, b: number, c: number, d: number, e: number, f: number): this;
}

Image Manipulation

Selection Management

Crop selection areas with precise control over dimensions, aspect ratios, and interactive handles.

class CropperSelection extends CropperElement {
  x: number;
  y: number;
  width: number;
  height: number;
  aspectRatio: number;
  movable: boolean;
  resizable: boolean;
  zoomable: boolean;
  
  $change(x: number, y: number, width?: number, height?: number, aspectRatio?: number): this;
  $toCanvas(options?: CanvasOptions): Promise<HTMLCanvasElement>;
}

Selection Management

Utility Functions

Comprehensive set of utility functions for type checking, event handling, DOM manipulation, and mathematical operations.

// Type checking
function isString(value: unknown): value is string;
function isNumber(value: unknown): value is number;
function isElement(node: unknown): node is Element;

// Event handling
function on(target: EventTarget, types: string, listener: EventListenerOrEventListenerObject): void;
function off(target: EventTarget, types: string, listener: EventListenerOrEventListenerObject): void;
function emit(target: EventTarget, type: string, detail?: unknown): boolean;

// Geometry utilities
function getOffset(element: Element): { left: number; top: number };
function multiplyMatrices(matrix: number[], ...args: number[][]): number[];

Utility Functions

Additional Components

Specialized cropping interface elements including interactive handles, grid overlays, crosshairs, shading, and viewer functionality.

class CropperHandle extends CropperElement {
  action: string;
  plain: boolean;
  themeColor: string;
}

class CropperGrid extends CropperElement {
  bordered: boolean;
  columns: number;
  covered: boolean;
  rows: number;
  themeColor: string;
}

class CropperCrosshair extends CropperElement {
  centered: boolean;
  themeColor: string;
}

class CropperShade extends CropperElement {
  x: number;
  y: number;
  width: number;
  height: number;
  themeColor: string;
  $change(x: number, y: number, width?: number, height?: number): this;
  $reset(): this;
  $render(): this;
}

class CropperViewer extends CropperElement {
  resize: string;
  selection: string;
}

Additional Components

Constants and Events

// Element tag names
const CROPPER_CANVAS: string;
const CROPPER_IMAGE: string;
const CROPPER_SELECTION: string;
const CROPPER_HANDLE: string;
const CROPPER_GIRD: string;
const CROPPER_CROSSHAIR: string;
const CROPPER_SHADE: string;
const CROPPER_VIEWER: string;

// Action constants
const ACTION_MOVE: string;
const ACTION_SCALE: string;
const ACTION_ROTATE: string;
const ACTION_SELECT: string;
const ACTION_NONE: string;
const ACTION_TRANSFORM: string;

// Event constants
const EVENT_ACTION: string;
const EVENT_ACTION_START: string;
const EVENT_ACTION_END: string;
const EVENT_ACTION_MOVE: string;
const EVENT_CHANGE: string;
const EVENT_TRANSFORM: string;

Template

const DEFAULT_TEMPLATE: string;

Default HTML template containing the complete cropper structure with canvas, image, selection, handles, and grid elements.

Install with Tessl CLI

npx tessl i tessl/npm-cropperjs
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/cropperjs@2.0.x
Publish Source
CLI
Badge
tessl/npm-cropperjs badge