Skip to content

Your first compressed image ​

Start with one local image and a JPEG output. Add byte targets, format fallbacks, and cancellation when the basic integration is working.

Requires Android 23+ or iOS 13.4+ and a rebuilt native application.

Published package and source candidate

npm latest is 0.4.0. It has a known iOS orientation defect that can vertically invert output pixels. The 0.4.1 source candidate fixes it and adds removeCompressionOutput, but is not published. Validate iOS output orientation before shipping an integration; see the release notes.

1. Install and rebuild the native app ​

bash
npm install react-native-image-compression-kit

Follow the Bare React Native or Expo development build instructions to install pods where needed and rebuild. A Metro reload is not enough. Expo Go and Snack cannot load the native module.

2. Compress a local image ​

Pass an image URI returned by your picker or camera. The function below uses APIs available in the published package:

ts
import { compressImage } from 'react-native-image-compression-kit';

async function compressLocalImage(localImageUri: string) {
  return compressImage({
    source: { uri: localImageUri },
    resize: { maxWidth: 1600, maxHeight: 1600, mode: 'contain' },
    output: { format: 'jpeg', quality: 82 },
    metadata: 'safe',
  });
}

The result contains uri, width, height, byteSize, originalByteSize, format, and compressionRatio. It points to a new cache file; the source is unchanged. A smaller output is not guaranteed for every input.

Android accepts app-readable file:// and content:// URIs. On iOS, prefer a local file:// URI. Remote URLs, data: URIs, and cloud-only assets must be materialized locally by the host app first. See picker integration.

3. Apply your upload policy ​

For JPEG or supported WebP output, add maxBytes to the output options. An unreachable target returns the smallest generated candidate, so check result.byteSize before uploading. PNG does not support maxBytes.

ts
const output = { format: 'jpeg', quality: 82, maxBytes: 500_000 } as const;

Keep ownership of the cache file explicit. Upload or copy it, then remove the temporary output using your app's file API. Clean it up when you reject it for exceeding the upload policy too. The 0.4.1 candidate offers removeCompressionOutput for package-owned output cleanup; that API is not in npm 0.4.0.

Choose your next step ​

You need to…Continue with
Support a gallery or camera pickerImage picker integration
Choose WebP with a JPEG fallbackCapabilities and fallbacks
Set a byte budget or cancel workCompression recipes
Understand file ownership and privacyOutput files and metadata
Diagnose a native build or URI errorErrors and troubleshooting
Inspect real native outputsNative result demo

Native output claims are capability-driven and evidence-backed.