super-image-cropper

🖼️ Super Image Cropper

A powerful JavaScript image cropping library that supports GIF animations, PNG, JPG and other image formats.

🌟 Live Demo | 📖 Documentation | 🇨🇳 中文文档

✨ Features

• 🎬 GIF Animation Support - Crop animated GIFs while preserving animation
• 🖼️ Multiple Formats - Support for PNG, JPG, JPEG, and GIF formats
• 🔧 CropperJS Integration - Seamless integration with popular CropperJS library
• 🎨 Flexible Output - Multiple output formats: Base64, Blob, or Blob URL
• ⚡ High Performance - Optimized for handling large images and animations
• 🎯 Precise Control - Fine-grained control over cropping parameters
• 📱 Cross-Platform - Works in all modern browsers
• 🔄 Transform Support - Rotation and scaling transformations

🎯 Live Demo

• Online Demo - Try it out in your browser
• CodeSandbox - Interactive example with CropperJS

Preview

GIF Animation Cropping

Static Image Cropping

🚀 Quick Start

Installation

npm install super-image-cropper

yarn add super-image-cropper

pnpm add super-image-cropper

Basic Usage

With CropperJS (Recommended)

<img id="image" src="your-image.gif" alt="Image to crop">

import { SuperImageCropper } from 'super-image-cropper';
import Cropper from 'cropperjs';

// Initialize CropperJS
const image = document.getElementById('image') as HTMLImageElement;
const cropperInstance = new Cropper(image, {
  aspectRatio: 16 / 9,
  autoCrop: false,
  autoCropArea: 1,
  minCropBoxHeight: 10,
  minCropBoxWidth: 10,
  viewMode: 1,
  initialAspectRatio: 1,
  responsive: false,
  guides: true
});

// Create cropper instance
const imageCropper = new SuperImageCropper();

// Crop the image
imageCropper.crop({
  cropperInstance: cropperInstance,
  src: 'your-image.gif',
  outputType: 'blobURL' // optional, default is blobURL
}).then(blobUrl => {
  const img = document.createElement('img');
  img.src = blobUrl;
  document.body.appendChild(img);
});

Standalone Usage

import { SuperImageCropper } from 'super-image-cropper';

const imageCropper = new SuperImageCropper();

imageCropper.crop({
  src: 'your-image.gif',
  cropperJsOpts: {
    width: 400,
    height: 240,
    rotate: 45,
    x: 0,
    y: 0,
    scaleX: 1,
    scaleY: 1
  },
  outputType: 'base64'
}).then(result => {
  console.log('Cropped image:', result);
});

📖 API Reference

SuperImageCropper

Methods

crop(options: CropOptions): Promise<string | Blob>

Crops an image based on the provided options.

CropOptions

Property	Type	Required	Description
src	string	Yes	Image URL or path
crossOrigin	string	No	CORS strategy for image loading
cropperInstance	Cropper	No	CropperJS instance (when used with CropperJS)
cropperJsOpts	CropperJsOptions	No	Manual cropping parameters
gifJsOptions	object	No	gif.js configuration
outputType	'base64' | 'blob' | 'blobURL'	No	Output format (default: 'blobURL')

CropperJsOptions

Property	Type	Description
x	number	Left offset of the cropped area
y	number	Top offset of the cropped area
width	number	Width of the cropped area
height	number	Height of the cropped area
rotate	number	Rotation angle in degrees
scaleX	number	Horizontal scaling factor
scaleY	number	Vertical scaling factor
background	string	Background color for GIF (optional)

Output Types

• base64 - Returns a base64 encoded string
• blob - Returns a Blob object
• blobURL - Returns a blob URL (e.g., blob:http://localhost:3000/8a583ca5...)

🔧 Examples

React Integration

Check out our React example for a complete implementation with React and CropperJS.

Advanced Usage

import { SuperImageCropper } from 'super-image-cropper';

const cropper = new SuperImageCropper();

// Crop with custom GIF options
await cropper.crop({
  src: 'animated.gif',
  cropperJsOpts: {
    x: 100,
    y: 100,
    width: 300,
    height: 200,
    rotate: 90,
    background: '#ffffff'
  },
  gifJsOptions: {
    quality: 10,
    workers: 2,
    workerScript: 'gif.worker.js'
  },
  outputType: 'blob'
});

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/STDSuperman/super-image-cropper.git

# Install dependencies
pnpm install

# Build the project
pnpm build

Project Structure

super-image-cropper/
├── packages/
│   ├── super-image-cropper/    # Main library
│   └── gif-worker-js/          # GIF processing worker
├── example/                    # Example applications
├── docs/                       # Documentation
└── scripts/                    # Build and release scripts

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• CropperJS - Excellent image cropping library
• gif.js - GIF encoding library
• All our contributors

📞 Support

• 🐛 Report Issues
• 💬 Discussions
• ⭐ Star this project if it helps you!

Made with ❤️ by STDSuperman