Browser library

Add on-device background removal to your own web app with @bg0/browser.

@bg0/browser is the engine behind bg0.dev. It loads the BiRefNet-lite ONNX model, runs it with WebGPU or WebAssembly, and returns a transparent PNG. No server, no API key.

Install

npm install @bg0/browser

pnpm add @bg0/browser

yarn add @bg0/browser

bun add @bg0/browser

nub add @bg0/browser

aube add @bg0/browser

Remove a background

import { removeBackground } from '@bg0/browser'

const result = await removeBackground(file, {
  quality: 'quality',
  onProgress: ({ stage, progress, message }) => console.log(stage, progress, message),
})

const url = URL.createObjectURL(result.blob)

file is any Blob, such as a File from an input or a drop event. PNG, JPG, and WebP up to 40 MB are accepted.

Options

Option	Type	Default	Meaning
`quality`	`'fast' \| 'quality'`	`'fast'`	Mask smoothing level. `quality` costs a little time and gives cleaner edges
`onProgress`	`(progress) => void`		Called through the `preparing`, `downloading`, `processing`, and `finishing` stages
`signal`	`AbortSignal`		Cancel a run. The promise rejects with a `BackgroundRemovalError`

Result

Field	Type	Meaning
`blob`	`Blob`	PNG with alpha
`width`, `height`	`number`	Pixel size of the output
`provider`	`'webgpu' \| 'wasm'`	Which backend ran the model
`durationMs`	`number`	Wall time for the whole call

Errors

Every failure is a BackgroundRemovalError with a stable code and a message written for end users, so you can show it directly.

import { BackgroundRemovalError } from '@bg0/browser'

try {
  await removeBackground(file)
} catch (error) {
  if (error instanceof BackgroundRemovalError) toast(error.message)
}

Capabilities

import { getBrowserCapabilities } from '@bg0/browser'

const { webgpu } = getBrowserCapabilities()

Use this to warn users on the WASM path that a large photo will take longer.

The model is fetched from the Hugging Face hub and kept in browser storage. Calls in the same page reuse the initialized model. After a reload, BG0 reuses the stored files but still initializes ONNX and uploads weights to WebGPU. Browsers may evict the files under storage pressure. clearModelCache() forces a download on the next call.