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

JavaScript API

Name: tessl/npm-cropperjs
Author: tessl

Core JavaScript interface for creating and managing cropper instances. The main Cropper class provides programmatic access to all cropping functionality and serves as the primary entry point for JavaScript-based integration.

Capabilities

Cropper Class

Main class for creating and managing image cropper instances.

/**
 * Main cropper class for creating image cropping interfaces
 */
class Cropper {
  /** Library version string */
  static version: string;
  
  /** The source image or canvas element */
  element: HTMLImageElement | HTMLCanvasElement;
  
  /** Configuration options for the cropper */
  options: CropperOptions;
  
  /** Container element where cropper is rendered */
  container: Element;
  
  /**
   * Create a new Cropper instance
   * @param element - Image or canvas element, or CSS selector string
   * @param options - Configuration options
   */
  constructor(
    element: HTMLImageElement | HTMLCanvasElement | string,
    options?: CropperOptions
  );
  
  /**
   * Get the cropper canvas element
   * @returns The canvas element or null if not found
   */
  getCropperCanvas(): CropperCanvas | null;
  
  /**
   * Get the cropper image element
   * @returns The image element or null if not found
   */
  getCropperImage(): CropperImage | null;
  
  /**
   * Get the first cropper selection element
   * @returns The first selection element or null if not found
   */
  getCropperSelection(): CropperSelection | null;
  
  /**
   * Get all cropper selection elements
   * @returns NodeList of all selection elements or null if none found
   */
  getCropperSelections(): NodeListOf<CropperSelection> | null;
}

Usage Examples:

import Cropper from 'cropperjs';

// Create from DOM element
const imageElement = document.getElementById('my-image');
const cropper = new Cropper(imageElement);

// Create with options
const cropper = new Cropper(imageElement, {
  container: document.getElementById('cropper-container'),
  template: '<cropper-canvas><cropper-image></cropper-image></cropper-canvas>'
});

// Create from selector string
const cropper = new Cropper('#my-image');

// Access cropper elements
const canvas = cropper.getCropperCanvas();
const image = cropper.getCropperImage();
const selection = cropper.getCropperSelection();

// Check version
console.log(Cropper.version);

Configuration Options

Configuration interface for customizing cropper behavior.

/**
 * Configuration options for Cropper instances
 */
interface CropperOptions {
  /**
   * Container element where the cropper will be rendered
   * Can be a DOM element or CSS selector string
   * Defaults to the parent element of the source image
   */
  container?: Element | string;
  
  /**
   * HTML template for the cropper structure
   * Defaults to DEFAULT_TEMPLATE if not provided
   */
  template?: string;
}

Usage Examples:

// Minimal configuration
const cropper = new Cropper('#image');

// Custom container
const cropper = new Cropper('#image', {
  container: '#my-container'
});

// Custom template
const cropper = new Cropper('#image', {
  template: `
    <cropper-canvas background>
      <cropper-image rotatable scalable></cropper-image>
      <cropper-selection movable resizable>
        <cropper-grid></cropper-grid>
      </cropper-selection>
    </cropper-canvas>
  `
});

Element Access Methods

Methods for accessing the web component elements created by the cropper.

/**
 * Get the cropper canvas element
 * The canvas handles user interactions and contains all other elements
 */
getCropperCanvas(): CropperCanvas | null;

/**
 * Get the cropper image element
 * The image element handles the source image display and transformations
 */
getCropperImage(): CropperImage | null;

/**
 * Get the first cropper selection element
 * Selection elements define crop areas
 */
getCropperSelection(): CropperSelection | null;

/**
 * Get all cropper selection elements
 * Useful when multiple selections are enabled
 */
getCropperSelections(): NodeListOf<CropperSelection> | null;

Usage Examples:

const cropper = new Cropper('#image');

// Get canvas for interaction control
const canvas = cropper.getCropperCanvas();
if (canvas) {
  canvas.disabled = true; // Disable interactions
  canvas.scaleStep = 0.2; // Change zoom sensitivity
}

// Get image for transformation control
const image = cropper.getCropperImage();
if (image) {
  image.rotatable = false; // Disable rotation
  await image.$ready(); // Wait for image to load
  image.$zoom(1.5); // Zoom to 150%
}

// Get selection for crop control
const selection = cropper.getCropperSelection();
if (selection) {
  selection.aspectRatio = 16/9; // Set aspect ratio
  selection.$change(50, 50, 200, 112.5); // Set specific crop area
}

// Handle multiple selections
const selections = cropper.getCropperSelections();
if (selections) {
  Array.from(selections).forEach((selection, index) => {
    console.log(`Selection ${index}:`, {
      x: selection.x,
      y: selection.y,
      width: selection.width,
      height: selection.height
    });
  });
}

Error Handling

The Cropper constructor will throw errors for invalid inputs:

try {
  // This will throw an error if element is not img or canvas
  const cropper = new Cropper(document.createElement('div'));
} catch (error) {
  console.error('Invalid element type:', error.message);
}

try {
  // This will throw an error if container selector is invalid
  const cropper = new Cropper('#image', {
    container: '#nonexistent-container'
  });
} catch (error) {
  console.error('Invalid container:', error.message);
}

Common errors: