@files-ui/compress

Image compression and optimization plugin for Files UI. Reduce file sizes client-side before upload.

Installation

npm install @files-ui/compress
# or
yarn add @files-ui/compress

Features

• ✅ Smart Compression — Reduces file size while preserving quality
• ✅ Resize Images — Set max width/height
• ✅ Format Conversion — Convert PNG → WebP/JPEG
• ✅ Quality Control — Adjustable quality settings
• ✅ TypeScript — Full type safety
• ✅ Zero Dependencies — Pure browser APIs
• ✅ Lightweight — Only ~8KB gzipped

Quick Start

import { Dropzone } from "@files-ui/react";
import { compressImage } from "@files-ui/compress";

function MyComponent() {
  const handleChange = async (files) => {
    const compressedFiles = await Promise.all(
      files.map(file => compressImage(file, {
        maxSizeMB: 1,
        maxWidthOrHeight: 1920,
        quality: 0.8
      }))
    );
    // Upload compressed files
  };
  
  return <Dropzone onChange={handleChange} />;
}

API Reference

compressImage(file, options)

Compresses an image file and returns a new ExtFile with reduced size.

Parameters:

| Param | Type | Default | Description | |-------|------|---------|-------------| | file | ExtFile | required | The file to compress | | options | CompressOptions | {} | Compression options |

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | maxSizeMB | number | Infinity | Target file size in MB | | maxWidthOrHeight | number | undefined | Max dimension (preserves aspect ratio) | | quality | number | 0.8 | Quality 0-1 (lower = smaller) | | format | "jpeg" \| "png" \| "webp" | (original) | Output format | | preserveMetadata | boolean | false | Keep EXIF data |

Returns: Promise<ExtFile>

compressImages(files, options)

Batch compress multiple files.

const compressed = await compressImages(files, {
  maxSizeMB: 1,
  quality: 0.8
});

useCompression(options)

React hook for automatic compression:

const { compressedFiles, isCompressing } = useCompression(files, {
  maxSizeMB: 1,
  maxWidthOrHeight: 1920
});

Examples

Basic Compression

import { compressImage } from "@files-ui/compress";

const compressed = await compressImage(file, {
  maxSizeMB: 1,
  quality: 0.8
});

console.log("Original:", file.size, "Compressed:", compressed.size);

Resize to Maximum Dimensions

const resized = await compressImage(file, {
  maxWidthOrHeight: 1920, // Max 1920px on longest side
  quality: 0.9
});

Convert Format

// Convert PNG to WebP for better compression
const webp = await compressImage(file, {
  format: "webp",
  quality: 0.85
});

With Dropzone

import { Dropzone } from "@files-ui/react";
import { compressImages } from "@files-ui/compress";

function SmartUpload() {
  const [files, setFiles] = useState([]);
  const [compressed, setCompressed] = useState([]);
  
  const handleChange = async (newFiles) => {
    setFiles(newFiles);
    
    // Compress images only
    const imageFiles = newFiles.filter(f => f.type?.startsWith("image/"));
    const otherFiles = newFiles.filter(f => !f.type?.startsWith("image/"));
    
    const compressedImages = await compressImages(imageFiles, {
      maxSizeMB: 2,
      maxWidthOrHeight: 2048,
      quality: 0.85
    });
    
    setCompressed([...compressedImages, ...otherFiles]);
  };
  
  return (
    <>
      <Dropzone onChange={handleChange} value={files} />
      <p>Original: {formatBytes(totalSize(files))}</p>
      <p>Compressed: {formatBytes(totalSize(compressed))}</p>
    </>
  );
}

Progressive Quality

// Try to hit target size with multiple quality levels
const result = await compressImage(file, {
  maxSizeMB: 0.5,
  quality: 0.9, // Start high
  // Will automatically reduce quality if needed
});

Performance Tips

1. Set realistic targets — Some images can't be compressed below a certain size
2. Use WebP format — Better compression than JPEG/PNG
3. Batch operations — Use compressImages() for multiple files
4. Async processing — Show loading indicator during compression
5. Skip small files — Don't compress files already under target size

Browser Support

Works in all modern browsers with Canvas API support:

• Chrome 60+
• Firefox 55+
• Safari 11+
• Edge 79+

License

MIT © JinSSJ3