@resizebox/background-remover

Browser-first AI background removal for JavaScript and TypeScript.

Built by ResizeBox.com, a privacy-focused image toolkit that processes images locally on the user's device.

Install

npm install @resizebox/background-remover

Quick start

import { removeBackground } from '@resizebox/background-remover';

const input = fileInput.files?.[0];
if (!input) throw new Error('Select an image first');

const result = await removeBackground(input, {
  onProgress(progress) {
    if (progress.phase === 'downloading-model') {
      console.log(`Downloading AI model: ${progress.progress}%`);
    }
  },
});

const url = URL.createObjectURL(result.blob);

The first run downloads the AI model from Hugging Face and can take longer. The browser cache is used for later runs.

Background colors

Transparent PNG is the default output. You can also composite the cutout onto a solid six-digit hex color:

const whiteBackground = await removeBackground(file, {
  background: '#ffffff',
});

Preload the model

Use preloadBackgroundRemovalModel() when you want to download and initialize the model before the user's first image is processed.

import { preloadBackgroundRemovalModel } from '@resizebox/background-remover';

await preloadBackgroundRemovalModel({
  onProgress(progress) {
    console.log(progress.phase, progress.progress);
  },
});

Backend selection

The default device is auto. When WebGPU is available, the package tries WebGPU first and falls back to WebAssembly if model loading or inference fails.

await removeBackground(file, { device: 'webgpu' });
await removeBackground(file, { device: 'wasm' });

Supported device values:

• auto
• webgpu
• wasm

Progress states

The onProgress callback can receive:

• loading-model
• downloading-model
• initializing
• fallback
• ready
• processing

downloading-model includes a progress percentage when the model host provides it.

API

removeBackground(input, options?)

Accepts a JPEG, PNG, or WebP Blob or File and returns a PNG Blob plus output metadata.

type RemoveBackgroundOptions = {
  device?: 'auto' | 'webgpu' | 'wasm';
  background?: 'transparent' | string;
  onProgress?: (progress: BackgroundRemovalProgress) => void;
};

The package validates MIME type, file signature, file size, image decoding, and decoded pixel count before model processing. Current limits are exported through backgroundRemoverConfig.

preloadBackgroundRemovalModel(options?)

Downloads and initializes the model without processing an image. Returns the selected backend.

resetBackgroundRemovalModel()

Clears the in-memory model instance so a later call can load it again. Browser-cached model data is not deleted.

BackgroundRemoverError

Validation, model loading, processing, canvas, and encoding failures throw BackgroundRemoverError. Use its code property for application-specific messages.

import {
  BackgroundRemoverError,
  removeBackground,
} from '@resizebox/background-remover';

try {
  await removeBackground(file);
} catch (error) {
  if (error instanceof BackgroundRemoverError) {
    console.error(error.code);
  }
}

Browser requirements

The package is intended for modern browsers and uses browser APIs such as:

• Blob
• createImageBitmap
• Canvas 2D or OffscreenCanvas
• WebAssembly
• WebGPU when available

The AI model is not bundled into this npm package. Model data is downloaded from onnx-community/ormbg-ONNX on Hugging Face on first use.

Privacy

Selected images are processed locally on the user's device. Image content is not uploaded to ResizeBox or Hugging Face. Hugging Face is used only to download AI model data.

For the interactive tool, visit ResizeBox.com.

License

MIT