Browser image compression library for JavaScript and TypeScript.
npm install @thaparoyal/image-compressionimage compression library for JavaScript and TypeScript, designed for browser and CDN usage. Offers extensive configuration, automatic format selection, and high-quality compression.
- Multiple output formats: WebP, JPEG, PNG, AVIF (auto-detects browser support)
- Five resize modes: contain, cover, fill, inside, outside
- Progressive JPEG support
- EXIF metadata preservation option
- Smart quality optimization using binary search
- Automatic downscaling for large images
- High-quality image rendering with smoothing
- TypeScript support with comprehensive type definitions
- Flexible configuration options
- Custom output filenames
- Automatic format fallbacks
- Detailed progress logging and error handling
``bash`
npm install @thaparoyal/image-compression
Use the CDN build for browser:
`html`
After including the script, you can use the library as a UMD module:
`javascript
// If using a bundler or module loader (like RequireJS, SystemJS, etc.)
const { compress } = ImageCompression;
// Basic compression
const file = document.querySelector('input[type="file"]').files[0];
const compressedFile = await compress(file, {
maxSizeMB: 0.5, // target size in megabytes
maxWidth: 1920, // maximum width in pixels
preferredFormat: 'webp' // preferred output format
});
// Advanced compression with all options
const compressedFile = await compress(file, {
maxSizeMB: 0.5,
maxWidth: 1920,
maxHeight: 1080,
preferredFormat: 'webp',
quality: 0.9,
resizeMode: 'cover',
preserveExif: true,
progressive: true,
debug: true,
outputFilename: 'compressed-image.webp',
downscaleDivisor: 4,
minQuality: 0.2,
});
`
Here's a complete example showing image compression with preview, size comparison, and all available options:
`html
Image Compression Demo
`
This example provides:
- Live image preview for both original and compressed images
- Size comparison and compression ratio
- UI controls for all compression options
- Progress indication
- Error handling
- Responsive layout
Compresses an image in the browser with options.
#### CompressionOptions
`typescript`
interface CompressionOptions {
maxSizeMB?: number; // Target maximum size in megabytes (default: 0.1)
quality?: number; // Starting compression quality 0-1 (default: 0.9)
maxWidth?: number; // Maximum width in pixels (default: 800)
maxHeight?: number | null; // Maximum height in pixels (default: null)
preferredFormat?: 'webp' | 'jpeg' | 'png' | 'avif'; // Preferred output format (default: 'webp')
preserveExif?: boolean; // Preserve EXIF metadata (default: false)
resizeMode?: 'contain' | 'cover' | 'fill' | 'inside' | 'outside'; // Resize mode (default: 'contain')
minQuality?: number; // Minimum allowed quality (default: 0.1)
progressive?: boolean; // Enable progressive JPEG (default: false)
debug?: boolean; // Enable debug logging (default: false)
outputFilename?: string; // Custom output filename
downscaleDivisor?: number; // Divisor for initial downscaling (default: 5)
}
#### Example: Custom Resize Mode
`javascript`
const compressedFile = await compress(file, {
maxSizeMB: 0.2,
maxWidth: 1024,
maxHeight: 768,
resizeMode: 'cover',
});
#### Example: Progressive JPEG
`javascript`
const compressedFile = await compress(file, {
preferredFormat: 'jpeg',
progressive: true,
});
#### Example: Preserve EXIF Metadata
`javascript`
const compressedFile = await compress(file, {
preserveExif: true,
});
#### Example: Custom Output Filename
`javascript`
const compressedFile = await compress(file, {
outputFilename: 'my-image.webp',
});
#### Example: Debug Logging
`javascript``
const compressedFile = await compress(file, {
debug: true,
});
- Uses browser canvas for resizing and format conversion
- Automatically selects the best supported format
- Optimizes quality using binary search to meet target size
- Preserves EXIF metadata if requested
- Supports all major browsers and CDN delivery
MIT © Thapa Royal