Universal background removal for React Native - removes backgrounds from any foreground objects using iOS 17+ Vision and Android MLKit Subject Segmentation with API fallback support.
- Universal Background Removal - Works with any foreground objects (people, cars, objects, etc.)
-
iOS 17+ Vision Framework - Native ML with
VNGenerateForegroundInstanceMaskRequest - Android MLKit Subject Segmentation - Google's powerful ML for object detection
- API Fallback Support - Graceful fallback for iOS 15.1-16.x versions
- Auto-Cropping - Automatically crops transparent pixels around detected objects
- Performance Optimized - Parallel processing for large images on multi-core devices
- CPU-Aware Processing - Adapts thread count based on device capabilities
yarn add @six33/react-native-bg-removalimport { removeBackground } from '@six33/react-native-bg-removal';
try {
// You can get the imageURI from the camera or gallery
// By default, transparent pixels are trimmed
const trimmedImageURI = await removeBackground(imageURI);
// To disable trimming use:
const untrimmedImageURI = await removeBackground(imageURI, { trim: false });
console.log('Success:', trimmedImageURI);
} catch (error) {
console.error('Background removal failed:', error.message);
}Removes the background from an image and returns the processed image URI.
Parameters:
-
imageURI(string): The URI of the image to process -
options(object, optional):-
trim(boolean, default:true): Iftrue, trims transparent pixels from the output image.
-
Returns:
-
Promise<string>: URI of the processed image with background removed
Throws:
-
'REQUIRES_API_FALLBACK': On iOS 15.1-16.x (use external API) -
Error: For processing failures or invalid input
Checks if native background removal is supported on the current device.
Returns:
-
Promise<boolean>:trueif native ML is supported,falseif API fallback is needed
For iOS 15.1-16.x versions, you can implement a fallback to external APIs. The recommended approach is to check for native support first:
import { removeBackground, isNativeBackgroundRemovalSupported } from '@six33/react-native-bg-removal';
async function processImage(imageURI) {
const isNativeSupported = await isNativeBackgroundRemovalSupported();
if (isNativeSupported) {
// Use fast, native ML for background removal
return await removeBackground(imageURI);
} else {
// Fallback to external API for older iOS versions
return await removeBackgroundWithAPI(imageURI);
}
}
async function removeBackgroundWithAPI(imageURI) {
const formData = new FormData();
formData.append('image', {
uri: imageURI,
type: 'image/jpeg',
name: 'image.jpg',
});
try {
const response = await fetch('https://[YOUR_BACKGROUND_REMOVAL_API]/remove-background', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'multipart/form-data',
},
body: formData,
});
if (!response.ok) {
throw new Error(`API Error: ${response.status}`);
}
const blob = await response.blob();
// Convert blob to base64 for cleaner data handling
return await convertBlobToBase64(blob);
} catch (error) {
console.error('API fallback failed:', error);
throw new Error('Background removal failed on all methods');
}
}
function convertBlobToBase64(blob) {
return new Promise((resolve, reject) => {
const reader = new FileReader();
reader.onload = () => {
resolve(reader.result); // Returns base64 data URI: "data:image/png;base64,..."
};
reader.onerror = reject;
reader.readAsDataURL(blob);
});
}If you'd like to host your own fallback API in Node.js, you can use the @imgly/background-removal-node package. Here's a minimal example:
// server.js
const express = require('express');
const multer = require('multer');
const os = require('os');
const fs = require('fs');
const { removeBackground } = require('@imgly/background-removal-node');
const upload = multer({ dest: os.tmpdir() });
const app = express();
app.post('/remove-background', upload.single('image'), async (req, res) => {
if (!req.file) {
return res.status(400).json({ error: 'No image file uploaded' });
}
const tempPath = req.file.path;
try {
const arrayBuffer = await removeBackground(tempPath);
const imageBase64 = Buffer.from(imageBuffer).toString('base64');
res.json({ imageBase64 });
} catch (err) {
res.status(500).json({ error: err.message });
} finally {
fs.unlink(tempPath, () => {}); // clean up temp file
}
});
app.listen(3000, () =>
console.log('Fallback API running on http://localhost:3000')
);Check device capabilities before processing:
import { isNativeBackgroundRemovalSupported } from '@six33/react-native-bg-removal';
async function checkCapabilities() {
const isNativeSupported = await isNativeBackgroundRemovalSupported();
if (isNativeSupported) {
console.log('Native ML background removal supported');
} else {
console.log('Will require API fallback for background removal');
}
}-
iOS 17+: Uses
VNGenerateForegroundInstanceMaskRequestfor universal object detection -
iOS 15.1-16.x: Throws
REQUIRES_API_FALLBACKerror for graceful API integration - Simulator: Returns original image with warning (Vision requires real device)
- API 24+: Uses MLKit Subject Segmentation for universal object detection
- Emulator: Fully supported (unlike iOS)
- Performance: Optimized with adaptive threading based on CPU cores
Automatically removes transparent pixels around detected objects:
- Reduces output file size
- Focuses on the detected subject
- Maintains aspect ratio
For large images (>1MP) on devices with 4+ CPU cores:
- 4 cores: Optimized 4-quadrant processing
- 6+ cores: Horizontal strip processing for better cache locality
- <4 cores: Sequential processing to avoid overhead
| Platform | Minimum Version | Features |
|---|---|---|
| iOS | 15.1+ | API fallback support |
| iOS | 17.0+ | Native universal background removal |
| Android | API 24+ | MLKit Subject Segmentation |
import { removeBackground } from '@six33/react-native-bg-removal';
try {
const result = await removeBackground(imageURI);
console.log('Success:', result);
} catch (error) {
switch (error.message) {
case 'REQUIRES_API_FALLBACK':
// Handle iOS 15.1-16.x fallback
console.log('Using API fallback...');
break;
case 'Invalid URL':
console.error('Please provide a valid image URI');
break;
case 'Unable to load image':
console.error('Could not load the specified image');
break;
default:
console.error('Unexpected error:', error.message);
}
}- Simulator not working: Vision framework requires a real device
- iOS 16 not working: Expected behavior, implement API fallback
- Slow processing: Normal for large images, consider resizing input
- App crashes on older devices: Check minimum API level 24
- MLKit model download: Automatic via Google Play services
- Performance: Ensure sufficient device memory for large images
Note: You need to use a real device on iOS to use this package. Vision framework requires actual device hardware. Android emulators are fully supported.
See the contributing guide to learn how to contribute to the repository and the development workflow.
MIT
Made with create-react-native-library