react-compress-images

react-compress-images

Tiny, framework-friendly utilities to compress images in the browser using browser-image-compression, with handy helpers for Base64 conversion.

• Minimal, typed API with ergonomic overloads
• Works with single or multiple files
• Returns either File/File[] or Base64 string(s)
• ESM + CJS builds with TypeScript types and tree-shaking

Install

npm install react-compress-images
# or
yarn add react-compress-images

Runtime: Browser environments (uses File, FileReader, and fetch).

Peer dependencies

These are declared in peerDependencies for compatibility with React apps:

• react (v18 or v19)
• react-dom (v18 or v19)

Note: The utilities themselves are framework-agnostic and can be used without React.

Quick start

Compress multiple images and get File[] back (default):

import { compressImages } from 'react-compress-images';

const inputFiles: File[] = Array.from(fileInput.files ?? []);
const compressedFiles = await compressImages({
  type: 'multiple',
  images: inputFiles,
});

Return Base64 strings instead:

const base64Images = await compressImages({
  type: 'multiple',
  images: inputFiles,
  returnAsBase64: true,
});

Compress a single image:

const compressedFile = await compressImages({
  type: 'single',
  image: file,
});

const base64 = await compressImages({
  type: 'single',
  image: file,
  returnAsBase64: true,
});

API Reference

compressImages(options)

Overloads provide precise return types based on type and returnAsBase64:

// Single image
function compressImages(options: {
  type: 'single';
  image: File;
  options?: import('browser-image-compression').Options;
  returnAsBase64: true;
}): Promise<string>;

function compressImages(options: {
  type: 'single';
  image: File;
  options?: import('browser-image-compression').Options;
  returnAsBase64?: false | undefined;
}): Promise<File>;

// Multiple images
function compressImages(options: {
  type: 'multiple';
  images: File[];
  options?: import('browser-image-compression').Options;
  returnAsBase64: true;
}): Promise<string[]>;

function compressImages(options: {
  type: 'multiple';
  images: File[];
  options?: import('browser-image-compression').Options;
  returnAsBase64?: false | undefined;
}): Promise<File[]>;

• options.options: forwarded to browser-image-compression.
  • Defaults: { maxSizeMB: 0.2, maxWidthOrHeight: 1920, useWebWorker: true }
• options.returnAsBase64: when true, returns Base64 string(s) instead of File/File[].

Behavior and edge cases:

• For type: 'multiple' with an empty images array, resolves to an empty array.
• For type: 'multiple', if compression fails, the function currently resolves to an empty array (matching the requested return type).
• For type: 'single', errors bubble up (reject), so wrap in try/catch as needed.

getBase64(file)

Converts a File/Blob to a Base64 data URL.

import { getBase64 } from 'react-compress-images';

const dataUrl = await getBase64(file);

convertB64ToFile(dataUrl, filename?, fallbackType?)

Converts a Base64 data URL to a File. Safer for large/unicode data than manual atob parsing; uses fetch(dataUrl).blob() under the hood.

import { convertB64ToFile } from 'react-compress-images';

const file = await convertB64ToFile(
  dataUrl,        // must start with "data:"
  'my-image',     // optional filename without extension
  'image/png'     // optional fallback MIME if the data URL lacks one
);

Notes:

• The resulting filename is ${filename}.${ext} inferred from the MIME (or fallbackType).
• Throws if dataUrl does not start with data:.

Usage examples

React

import { useState } from 'react';
import { compressImages } from 'react-compress-images';

export function ImageCompressor() {
  const [previews, setPreviews] = useState<string[]>([]);

  async function onChange(e: React.ChangeEvent<HTMLInputElement>) {
    const list = e.target.files;
    if (!list || list.length === 0) return;

    const files = Array.from(list);
    const base64 = await compressImages({
      type: 'multiple',
      images: files,
      returnAsBase64: true,
    });
    setPreviews(base64);
  }

  return (
    <div>
      <input type="file" multiple accept="image/*" onChange={onChange} />
      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, 160px)', gap: 12, marginTop: 12 }}>
        {previews.map((src, i) => (
          <img key={i} src={src} alt={`preview-${i}`} style={{ width: 160, height: 160, objectFit: 'cover' }} />
        ))}
      </div>
    </div>
  );
}

Vanilla TS/JS

import { compressImages } from 'react-compress-images';

const input = document.querySelector('input[type="file"]');
input?.addEventListener('change', async (e) => {
  const files = Array.from((e.target as HTMLInputElement).files ?? []);
  const result = await compressImages({ type: 'multiple', images: files });
  console.log(result);
});

Tips and best practices

• Validate inputs and MIME types if you accept arbitrary files from users.
• Tune maxSizeMB, maxWidthOrHeight, and initialQuality for your use case. See the browser-image-compression docs for all options.
• If you need raw binary instead of File, you can read the File back as ArrayBuffer or Blob after compression.

TypeScript

• Types are bundled. You can also import the option types:

import type { Options } from 'browser-image-compression';
import type { CompressImagesOptions } from 'react-compress-images';

FAQ

• Does this work in Node.js?
  • No. It relies on browser APIs: File, FileReader, and fetch for data URLs.
• Is React required?
  • No. Despite the package name, it is framework-agnostic and can be used in any browser app.

License

ISC © Ahmed Elsehrawy