React Native Zip Archive

Zip archive utility for React Native.

v9 is for React Native ≥ 0.70. New Architecture is recommended. Stay on v7 only for RN < 0.70.

| Your React Native | Install | |-------------------|---------| | < 0.70 | npm install react-native-zip-archive@^7.0.0 | | 0.70–0.81 | latest v9 (old architecture works; native rebuild required) | | 0.82+ | latest v9 (New Architecture only — RN ignores the opt-out flags) |

iOS: Version 7.0.0+ requires a deployment target of iOS 15.5+ to comply with App Store privacy policy.

Requirements

| Platform | Minimum Version | |----------|-----------------| | React Native | >= 0.70.0 | | React | >= 18.0.0 | | iOS | >= 15.5 | | Android | >= API 23 (Android 6.0) |

Old architecture (RN 0.70–0.81)

Do not stay on v7 for old architecture on RN 0.70+. Install latest v9 and rebuild native.

| Surface | How v9 loads when New Architecture is off | |---------|-------------------------------------------| | JS | TurboModuleRegistry.get('RNZipArchive'), then NativeModules.RNZipArchive | | Android | isTurboModule follows BuildConfig.IS_NEW_ARCHITECTURE_ENABLED; paper specs compile when new arch is off | | iOS | RCT_EXPORT_MODULE always; getTurboModule is #ifdef RCT_NEW_ARCH_ENABLED |

| RN | Android newArchEnabled=false | iOS RCT_NEW_ARCH_ENABLED=0 | Evidence | |----|--------------------------------|------------------------------|----------| | 0.82+ (playground-rn 0.83.9) | N/A — flag ignored | N/A — flag ignored | RN 0.82; zip/unzip Maestro on New Arch (e2e.yml) | | 0.81.6 (last opt-out) | compile + IS_NEW_ARCHITECTURE_ENABLED=false | compile + Legacy Architecture | .github/workflows/old-arch.yml (not device Maestro) | | 0.73–0.80 | same native paths as 0.81 | same | inferred; not separately built |

Reproduce the 0.81 compile (same as CI):

npx @react-native-community/[email protected] init RnzaOldArch --version 0.81.6 --pm npm --skip-git-init
cd RnzaOldArch && npm install /path/to/react-native-zip-archive
# Android: set newArchEnabled=false in android/gradle.properties, then assembleRelease
# iOS: set platform :ios, '15.5' in the Podfile, then RCT_NEW_ARCH_ENABLED=0 pod install

Comparison

| | This library | JSZip in React Native | Nitro (react-native-nitro-unzip / react-native-nitro-archive) | |---|---|---|---| | Zip / unzip | Native iOS + Android | Pure JS (not a native unzip) | Native via Nitro | | Password-protected zip | Yes | Fine for small in-memory archives | Check those packages | | Expo | Development builds / EAS (not Expo Go) | Can run in Expo Go | Native — needs a development build | | Extra native dependency | None beyond this package | None | react-native-nitro-modules | | Large files | Native I/O | Memory-heavy | Speed / extra-format claims | | Install base | Production RN apps | Very widely used as JS | Much smaller today |

Use this library for native zip/unzip on device. Use JSZip when you only need small archives in JS. Nitro may fit if you want additional archive formats and accept the extra Nitro dependency and smaller install base.

Installation

React Native (bare)

npm install react-native-zip-archive

iOS:

cd ios && pod install

New Architecture is recommended. See MIGRATION.md.

Expo

Works in Expo development builds / EAS. Does not work in Expo Go (this package includes custom native code).

npx expo install react-native-zip-archive

Add the config plugin in app.json:

{
  "expo": {
    "plugins": ["react-native-zip-archive"]
  }
}

See playground-expo for a working Expo Development Build example.

Usage

import {
  zip,
  zipWithPassword,
  unzip,
  unzipWithPassword,
  listContents,
  unzipAssets,
  cancel,
  subscribe,
  isPasswordProtected,
  getUncompressedSize,
  ErrorCodes,
  ZipError,
  DEFAULT_COMPRESSION,
  NO_COMPRESSION,
  BEST_SPEED,
  BEST_COMPRESSION
} from 'react-native-zip-archive'

Bare React Native — react-native-fs:

import { DocumentDirectoryPath } from 'react-native-fs'

Expo — playground-expo uses expo-file-system/legacy:

import * as FileSystem from 'expo-file-system/legacy'

const DocumentDirectoryPath = FileSystem.documentDirectory

List, extract a subset, and abort with AbortSignal:

const controller = new AbortController()

const entries = await listContents(`${DocumentDirectoryPath}/bundle.zip`)
const assets = entries
  .filter((entry) => !entry.isDirectory && entry.path.startsWith('assets/'))
  .map((entry) => entry.path)

await unzip(`${DocumentDirectoryPath}/bundle.zip`, `${DocumentDirectoryPath}/out`, {
  entries: assets,
  signal: controller.signal,
})

// controller.abort()  → rejects with ZipError code ERR_CANCELLED

zip / zipWithPassword / unzipAssets accept the same { signal } option. cancel() still aborts the in-flight native operation.

API

zip(source: string | string[], target: string, compressionLevelOrOptions?: number | { compressionLevel?: number, signal?: AbortSignal }): Promise<string>

Zip a folder (string) or an array of files to the target path.

• To zip a single file, pass it as an array: zip([file], target).
• Array items may also be directories: their contents are added recursively with entry paths relative to the listed directory (the directory's own name is not included). This behaves the same on Android and iOS. Empty directories are preserved on both platforms.
• compressionLevel applies on both platforms for folder and file-array sources.
• Or pass an options object: zip(source, target, { compressionLevel: BEST_SPEED, signal }).

Compression Level Constants:

• DEFAULT_COMPRESSION (-1)
• NO_COMPRESSION (0)
• BEST_SPEED (1)
• BEST_COMPRESSION (9)

const sourcePath = DocumentDirectoryPath
const targetPath = `${DocumentDirectoryPath}/myFile.zip`

zip(sourcePath, targetPath)
  .then((path) => console.log(`zip completed at ${path}`))
  .catch((error) => console.error(error))

zipWithPassword(source: string | string[], target: string, password: string, encryptionType?: string, compressionLevel?: number): Promise<string>

Zip with password protection.

• To zip a single file, pass it as an array: zipWithPassword([file], target, password).
• Array items may also be directories: their contents are added recursively with entry paths relative to the listed directory (the directory's own name is not included). This behaves the same on Android and iOS. Empty directories are preserved on both platforms.
• compressionLevel applies on both platforms for folder and file-array sources.

Encryption Types:

• 'STANDARD' — Traditional ZIP encryption / ZipCrypto (default). This is not PKWARE Strong Encryption. On Android this writes zip4j ZIP_STANDARD so iOS and common unzip tools can decrypt the archive.
• 'AES-128' — AES 128-bit
• 'AES-256' — AES 256-bit

iOS: Both AES-128 and AES-256 use AES-256 internally. File arrays honor encryptionType the same as folders. The default is ZipCrypto ('STANDARD'), including when the 4th argument is omitted — file arrays previously always wrote WinZip-AES. Pass 'AES-128' or 'AES-256' if you need AES. Prefer 'STANDARD' when the archive will be unzipped by Node, Java, or other non-WinZip tools.

const sourcePath = DocumentDirectoryPath
const targetPath = `${DocumentDirectoryPath}/myFile.zip`

zipWithPassword(sourcePath, targetPath, 'password', 'STANDARD')
  .then((path) => console.log(`zip completed at ${path}`))
  .catch((error) => console.error(error))

unzip(source: string, target: string, charset?: string | string[], entries?: string[]): Promise<string>

Unzip from source to target. Pass entries to extract only those paths; directory names match that entry and all nested children (e.g. 'docs' extracts docs/ and docs/readme.md).

You can pass entries as the third argument when using the default charset:

unzip(sourcePath, targetPath, ['readme.md', 'docs'])

Or with an explicit charset:

unzip(sourcePath, targetPath, 'UTF-8', ['readme.md', 'docs'])

Or with AbortSignal / selective extract as an options object:

unzip(sourcePath, targetPath, { entries: ['readme.md', 'docs'], signal })

The charset parameter defaults to UTF-8. On Android, other charsets are supported. On iOS, non-UTF-8 values reject with ERR_UNSUPPORTED.

const sourcePath = `${DocumentDirectoryPath}/myFile.zip`
const targetPath = DocumentDirectoryPath

unzip(sourcePath, targetPath, 'UTF-8')
  .then((path) => console.log(`unzip completed at ${path}`))
  .catch((error) => console.error(error))

unzipWithPassword(source: string, target: string, password: string, entries?: string[]): Promise<string>

Unzip a password-protected archive. Pass entries to extract only those paths.

unzipWithPassword(sourcePath, targetPath, 'password')
  .then((path) => console.log(`unzip completed at ${path}`))
  .catch((error) => console.error(error))

unzipWithPassword(sourcePath, targetPath, 'password', ['secret.txt'])
  .then((path) => console.log(`selective unzip completed at ${path}`))
  .catch((error) => console.error(error))

listContents(source: string, charset?: string): Promise<ZipEntry[]>

List archive entries without extracting.

type ZipEntry = {
  path: string
  size: number           // uncompressed size in bytes
  compressedSize: number
  isDirectory: boolean
  isEncrypted: boolean
}

The charset parameter defaults to UTF-8. On Android, other charsets are supported. On iOS, non-UTF-8 values reject with ERR_UNSUPPORTED.

listContents(sourcePath)
  .then((entries) => {
    entries.forEach((entry) => {
      console.log(entry.path, entry.size, entry.isDirectory)
    })
  })
  .catch((error) => console.error(error))

unzipAssets(assetPath: string, target: string): Promise<string>

Unzip a bundled archive.

• Android: relative path inside the APK assets/ folder (also accepts content:// URIs).
• iOS: relative path inside the main app bundle (e.g. a file copied with Xcode “Copy Bundle Resources”).

Do not pass an absolute filesystem path.

unzipAssets('./myFile.zip', DocumentDirectoryPath)
  .then((path) => console.log(`unzip completed at ${path}`))
  .catch((error) => console.error(error))

Optional { signal } as the third argument.

getUncompressedSize(source: string, charset?: string): Promise<number>

Returns the total uncompressed size of all files in the zip archive (in bytes).

The charset parameter is only supported on Android. On iOS it is ignored.

getUncompressedSize(sourcePath)
  .then((size) => console.log(`Uncompressed size: ${size} bytes`))
  .catch((error) => console.error(error))

cancel(): Promise<void>

Cancel the in-flight zip/unzip operation (best-effort). The active operation's promise rejects with ErrorCodes.CANCELLED (ERR_CANCELLED).

Zip/unzip work is serialized. Android runs operations on a single-thread executor; concurrent calls queue FIFO and do not run in parallel. iOS uses a background serial queue similarly, so cancel() is not blocked behind the operation it is meant to stop.

const unzipPromise = unzip(sourcePath, targetPath)
cancel()
unzipPromise.catch((error) => {
  if (error.code === ErrorCodes.CANCELLED) {
    console.log('unzip cancelled')
  }
})

Error codes

Native rejections use stable error.code values on both platforms:

| Code | When | |------|------| | ERR_FILE_NOT_FOUND | Source missing | | ERR_INVALID_PATH | Bad / null path | | ERR_INVALID_ARGS | Empty password, empty entries, etc. | | ERR_WRONG_PASSWORD | Password decrypt failed | | ERR_NOT_PASSWORD_PROTECTED | Password API used on a plain archive | | ERR_CORRUPT_ARCHIVE | Not a zip / truncated / unreadable | | ERR_UNSAFE_PATH | Zip Slip / path traversal | | ERR_CANCELLED | cancel() interrupted the operation | | ERR_ZIP / ERR_UNZIP | Generic zip/unzip failure | | ERR_UNSUPPORTED | API not available on this platform |

Also exported as the ErrorCodes constant map.

subscribe(callback: ({ progress: number, filePath: string }) => void): EmitterSubscription

Subscribe to progress events. Useful for showing a progress bar.

• progress — value from 0 to 1 (1 = completed)
• filePath — the zip file path (on iOS, the entry being processed for unzip operations; empty for zip operations)

Progress is reported monotonically from 0 to 1, with explicit 0% and 100% events at the start and end of each operation. The granularity depends on the operation:

• unzip / unzipWithPassword — byte-weighted: progress reflects uncompressed bytes extracted so far, updated after each entry completes.
• zip / zipWithPassword — per-file: progress reflects the number of files compressed so far.
• unzipAssets (Android only) — approximate: compares bytes read to the compressed archive size.

The event is global — check filePath in your callback to ensure it matches the operation you care about. Remember to call .remove() on the returned subscription when done.

import { useEffect } from 'react'

useEffect(() => {
  const sub = subscribe(({ progress, filePath }) => {
    console.log(`progress: ${progress}, file: ${filePath}`)
  })
  return () => sub.remove()
}, [])

Platform Support

| Feature | iOS | Android | Notes | |---------|-----|---------|-------| | zip (folder) | ✅ | ✅ | compressionLevel 0–9 | | zip (files array) | ✅ | ✅ | compressionLevel applies on both platforms | | zipWithPassword (folder) | ✅ | ✅ | Prefer STANDARD for server unzip | | zipWithPassword (files array) | ✅ | ✅ | iOS honors STANDARD vs AES; compressionLevel applies | | unzip | ✅ | ✅ | Optional entries; non-UTF-8 charset → ERR_UNSUPPORTED on iOS | | unzipWithPassword | ✅ | ✅ | Optional entries for selective extract | | listContents | ✅ | ✅ | Non-UTF-8 charset → ERR_UNSUPPORTED on iOS | | unzipAssets | ✅ | ✅ | Android assets/ (+ content://); iOS main bundle | | cancel | ✅ | ✅ | Best-effort mid-operation abort | | isPasswordProtected | ✅ | ✅ | — | | getUncompressedSize | ✅ | ✅ | Non-UTF-8 charset → ERR_UNSUPPORTED on iOS | | Progress Events | ✅ | ✅ | File path empty on iOS for zip |

Cross-Platform Notes

• Compression levels: Android and iOS apply compressionLevel (0–9) for folder and file-array zip / zipWithPassword.
• Encryption: Android supports AES-128, AES-256, and Standard ZIP encryption for all operations. On iOS, pass 'STANDARD' (default) for ZipCrypto archives that Node unzipper / Java ZipInputStream can read; 'AES-128' / 'AES-256' produce WinZip-AES archives that many server tools cannot open.
• Charset: Android supports custom charsets (default UTF-8). iOS accepts only UTF-8; other values reject with ERR_UNSUPPORTED.
• unzipAssets: Android reads assets/ (and content://). iOS reads from the main app bundle using the same relative path.
• Empty directories: Preserved when zipping directory contents via a files/folders array on both platforms.
• Concurrent operations: Android zip/unzip run on a single-thread executor; concurrent calls queue FIFO and do not run in parallel. iOS uses a background serial queue similarly (so cancel() is not blocked behind in-flight work).

Server-side unzip interoperability

Plain (non-AES) zips created on iOS and Android are intended to open with common server unzippers (unzip, Node unzipper, Java ZipInputStream). Practical tips:

• Prefer zip(...) or zipWithPassword(..., 'STANDARD') when the archive will be extracted off-device.
• Avoid AES password zips if the consumer is stock Java/unzipper — use 'STANDARD' instead.
• Decode URL-encoded paths (decodeURIComponent) before passing them in; %20 in paths has been mistaken for corrupt archives (#333).
• After upgrading, you can sanity-check a produced file with:

node scripts/validate-zip-header.js /path/to/archive.zip

CI and the npm publish workflow also extract a committed non-password fixture with Node unzipper and Java ZipInputStream (npm run test:interop). A WinZip-AES archive fails that gate — that was the #333 / #323 class of iOS default-AES zips.

Expo

Works in Expo development builds / EAS only — not Expo Go. Install and plugin setup are under Installation. See playground-expo for a working example.

Playground

Two fully-featured playground apps are included to demonstrate every API method:

• playground-expo — Expo SDK 55 with Expo Router (New Architecture)
• playground-rn — Bare React Native 0.83.9 (New Architecture)

Both apps consume the local library via file:.. and include Maestro E2E tests.

Migrating

Coming from v7? Start with Upgrade from v7. See MIGRATION.md for v7 → v8, v8 → v9.0, and v9.2–v9.4 notes.

Security

See SECURITY.md for supported versions and how to report vulnerabilities.

Testing

npm test

Contributing

See the playground apps for testing and contribution reference.

Related Projects

• ZipArchive
• zip4j