React Native Zip Archive

Zip archive utility for React Native.

v8.0 requires React Native ≥ 0.70 with New Architecture enabled. For older RN versions, use v7.x:

npm install react-native-zip-archive@^7.0.0

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)

Installation

npm install react-native-zip-archive

iOS:

cd ios && pod install

To enable New Architecture, see MIGRATION.md.

Usage

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

You may also want to use react-native-fs to access the file system:

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

API

zip(source: string | string[], target: string, compressionLevel?: number): 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, except that empty directories are preserved on Android only.
• compressionLevel is ignored on iOS when the source is a file array. Use a directory source for custom compression on iOS.

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, except that empty directories are preserved on Android only.
• compressionLevel is ignored on iOS when the source is a file array.

Encryption Types:

• 'STANDARD' — Standard ZIP encryption (default)
• 'AES-128' — AES 128-bit
• 'AES-256' — AES 256-bit

iOS: Both AES-128 and AES-256 use AES-256 internally. AES encryption is not supported for file arrays on iOS — only STANDARD works.

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): Promise<string>

Unzip from source to target.

The charset parameter is only supported on Android (default: UTF-8). On iOS it is ignored.

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): Promise<string>

Unzip a password-protected archive.

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

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

Unzip a file from the Android assets folder. Android only.

assetPath is the relative path inside the pre-bundled assets folder (e.g. folder/myFile.zip). Do not pass an absolute path.

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

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))

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)	✅	✅	—
zip (files array)	✅	✅	Compression level ignored on iOS
zipWithPassword (folder)	✅	✅	AES encryption supported
zipWithPassword (files array)	⚠️	✅	iOS: only STANDARD encryption
unzip	✅	✅	Charset ignored on iOS
unzipWithPassword	✅	✅	—
unzipAssets	❌	✅	Android only
isPasswordProtected	✅	✅	—
getUncompressedSize	✅	✅	Charset ignored on iOS
Progress Events	✅	✅	File path empty on iOS for zip

Cross-Platform Notes

• Compression levels: Android supports 0–9 for all operations. iOS supports them only for folder operations.
• Encryption: Android supports AES-128, AES-256, and Standard ZIP encryption for all operations. iOS supports AES and Standard for folders, but only Standard for file arrays.
• Charset: Android supports custom charsets (default UTF-8). iOS always uses UTF-8.
• unzipAssets: Supports assets/ folder and content:// URIs on Android. Not supported on iOS.

Expo

This library requires an Expo Development Build and does not work in Expo Go because it includes custom native code. See playground-expo for a working Expo Development Build 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 from v7

See MIGRATION.md for detailed migration instructions.

Testing

npm test

Contributing

See the playground apps for testing and contribution reference.

Related Projects

• ZipArchive
• zip4j

---