ArmpitCropper

English | 简体中文

A powerful image cropper for Ant Design Upload with advanced quality control and file size management.

✨ Features

• 🖼️ Image Cropping: Support for rectangular and circular cropping
• 🔍 Zoom Control: Adjustable image zoom with slider
• 🔄 Rotation: Image rotation functionality
• 📐 Aspect Ratio: Dynamic aspect ratio adjustment
• 🎛️ Quality Control: Real-time image quality adjustment with compression preview
• 📊 File Size Management: Real-time file size display and limit enforcement
• 🚫 Size Limits: Configurable maximum file size with visual warnings
• 🎨 Grid Display: Optional cropping grid overlay
• 🔄 Reset Function: One-click reset for all adjustments
• 🌐 i18n Support: Automatic language detection
• 📱 Responsive: Mobile-friendly design

📦 Installation

pnpm add armpit-cropper

🚀 Quick Start

import { Upload } from 'antd';
import ArmpitCropper from 'armpit-cropper';
import 'armpit-cropper/dist/style.css'; // import styles

const Demo = () => (
  <ArmpitCropper>
    <Upload>+ Add image</Upload>
  </ArmpitCropper>
);

🎮 Demo

Clone the repository and run the demo:

git clone https://github.com/name-q/ArmpitCropper.git
cd ArmpitCropper
pnpm install
pnpm run dev

Open your browser and visit http://localhost:5173 to see the demo.

📖 API

Prop	Type	Default	Description
quality	number	0.8	Image quality (0-1)
fillColor	string	'white'	Fill color for cropped image
maxFileSize	string | number	'2MB'	Maximum file size (e.g., '100KB', '2MB', '1.5GB')
outputType	string	'image/jpeg'	Output MIME type used for preview calculation and final export. Use 'image/jpeg' or 'image/webp' to make the quality slider effective; 'image/png' ignores quality.
renameWithTimestamp	boolean	true	When true, export filename uses a timestamp (e.g., 1694500000000.jpg) instead of the original name.
enableZoom	boolean	true	Enable zoom slider
enableRotation	boolean	false	Enable rotation slider
enableAspectRatio	boolean	false	Enable aspect ratio slider
enableQuality	boolean	true	Enable quality slider
showResetBtn	boolean	false	Show reset button
aspectRatio	number	1	Crop aspect ratio
minZoom	number	1	Minimum zoom level
maxZoom	number	3	Maximum zoom level
minQuality	number	0.1	Minimum quality
maxQuality	number	1.0	Maximum quality
cropShape	'rect' | 'round'	'rect'	Crop shape
showGrid	boolean	false	Show crop grid
modalTitle	string	'Edit image'	Modal title
modalWidth	number | string	-	Modal width
beforeCrop	function	-	Callback before crop modal opens

🔥 Advanced Features

Quality Control

The quality slider allows real-time adjustment of image compression with live file size preview:

<ArmpitCropper
  enableQuality={true}
  minQuality={0.1}
  maxQuality={1.0}
  quality={0.8}
>
  <Upload>Upload</Upload>
</ArmpitCropper>

Output Type

The previewed size and the final exported file use the same MIME type via outputType. Lossy formats (JPEG/WebP) respond to quality changes; PNG ignores quality changes.

// Export as JPEG (default) – quality slider affects size
<ArmpitCropper outputType="image/jpeg" quality={0.8} enableQuality>
  <Upload>Upload</Upload>
</ArmpitCropper>

// Export as WebP – quality slider affects size
<ArmpitCropper outputType="image/webp" quality={0.8} enableQuality>
  <Upload>Upload</Upload>
</ArmpitCropper>

// Export as PNG – quality slider will not change size (PNG is lossless)
<ArmpitCropper outputType="image/png" enableQuality>
  <Upload>Upload</Upload>
</ArmpitCropper>

File Size Limits

Set maximum file size with automatic validation:

<ArmpitCropper
  maxFileSize="1MB"
  enableQuality={true}
>
  <Upload>Upload</Upload>
</ArmpitCropper>

Supported file size formats:

• '100KB' or '100kb' - 100 kilobytes
• '2MB' or '2mb' - 2 megabytes
• '1.5GB' or '1.5gb' - 1.5 gigabytes
• 1048576 - Raw bytes (1MB)

When the file size exceeds the limit:

• The OK button is disabled
• A red warning message appears
• File size is displayed in red

Complete Example

import React from 'react';
import { Upload, Button } from 'antd';
import { UploadOutlined } from '@ant-design/icons';
import ArmpitCropper from 'armpit-cropper';

const App = () => {
  return (
    <ArmpitCropper
      enableZoom
      enableRotation
      enableAspectRatio
      enableQuality
      showResetBtn
      maxFileSize="2MB"
      quality={0.8}
      aspectRatio={16/9}
      cropShape="rect"
      showGrid
    >
      <Upload>
        <Button icon={<UploadOutlined />}>
          Upload Image
        </Button>
      </Upload>
    </ArmpitCropper>
  );
};

export default App;

📄 License

MIT License (c) name-q