file-compressor

Capacitor File Compressor Plugin

Capacitor plugin for efficient file compression with support for image formats like PNG, JPEG, and WebP.

Features

The Capacitor File Compressor plugin offers one of the most complete file compression solutions for Capacitor apps. Here are some of the key features:

• 🖥️ Cross-platform: Supports Android, iOS and Web.
• 🌅 Compress Images: Compress png, jpeg, and webp images.
• 🤝 Compatibility: Compatible with the Zip plugin.
• 📦 CocoaPods & SPM: Supports CocoaPods and Swift Package Manager for iOS.
• 🔁 Up-to-date: Always supports the latest Capacitor version.
• ⭐️ Support: Priority support from the Capawesome Team.
• ✨ Handcrafted: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just open an issue and we'll take a look!

Use Cases

The File Compressor plugin is typically used to shrink images before they leave the device, for example:

• Image uploads: Compress photos before uploading them to a server to save bandwidth and speed up uploads.
• Storage savings: Reduce the size of images before storing them on the device or in the cloud.
• Thumbnails and previews: Use the width and height options to create smaller versions of images for lists and galleries.
• Format conversion: Convert PNG images to smaller JPEG or WebP files using the mimeType option.

Compatibility

Plugin Version	Capacitor Version	Status
8.x.x	>=8.x.x	Active support
7.x.x	7.x.x	Deprecated
6.x.x	6.x.x	Deprecated

Demo

A working example can be found here.

Android

Guides

• Exploring the Capacitor File Compressor API

Installation

This plugin is only available to Capawesome Insiders. First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>

Attention: Replace <YOUR_LICENSE_KEY> with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a Capawesome Insider.

Next, you can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-file-compressor` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capawesome-team/capacitor-file-compressor
npx cap sync

Android

Proguard

If you are using Proguard, you need to add the following rules to your proguard-rules.pro file:

-keep class io.capawesome.capacitorjs.plugins.** { *; }

Variables

If needed, you can define the following project variable in your app’s variables.gradle file to change the default version of the dependency:

• $androidxDocumentFileVersion version of androidx.documentfile:documentfile (default: 1.1.0)

This can be useful if you encounter dependency conflicts with other plugins in your project.

Configuration

No configuration required for this plugin.

Usage

The following example shows how to compress an image while controlling its quality and dimensions.

Compress an image

Compress a PNG, JPEG, or WebP image by passing its path (Android and iOS) or blob (Web). Use the quality option to control the compression level and the optional width and height options to resize the image:

import { FileCompressor } from '@capawesome-team/capacitor-file-compressor';

const compressImage = async () => {
  const { path } = await FileCompressor.compressImage({
    height: 1000,
    mimeType: 'image/jpeg',
    path: 'content://com.android.providers.downloads.documents/document/msf%3A1000000485',
    quality: 0.7,
    width: 1000,
  });
  return path;
};

API

• compressImage(...)
• Interfaces

compressImage(...)

compressImage(options: CompressImageOptions) => Promise<CompressImageResult>

Compress an image.

Only png, jpeg, and webp images are supported.

Attention: The exif data of the image is lost during compression.

Param	Type
options	CompressImageOptions

Returns: Promise<CompressImageResult>

Since: 5.0.0

---

Interfaces

CompressImageResult

Prop	Type	Description	Since
path	string	The path of the compressed file. Only available on Android and iOS.	5.0.0
blob	Blob	The blob of the compressed file. Only available on Web.	5.0.0

CompressImageOptions

Prop	Type	Description	Default	Since
blob	Blob	The blob of the file to compress. Only available on Web.		5.0.0
height	number	The height of the resulting image.		7.1.0
mimeType	string	The mime type of the compressed file. On Android, only image/jpeg and image/webp are supported. On iOS, only image/jpeg is supported. On Web, only image/jpeg and image/webp are supported.	'image/jpeg'	5.0.0
path	string	The path of the file to compress. Only available on Android and iOS.		5.0.0
quality	number	The quality of the resulting image, expressed as a value from 0.0 to 1.0. The value 0.0 represents the maximum compression (or lowest quality) while the value 1.0 represents the least compression (or best quality).	0.6	5.0.0
width	number	The width of the resulting image.		7.1.0

FAQ

Which image formats are supported?

The plugin can compress PNG, JPEG, and WebP images. The output format is controlled by the mimeType option: on Android and Web, image/jpeg and image/webp are supported, while on iOS only image/jpeg is supported. The default output format is image/jpeg.

How do I control the compression quality?

Use the quality option, which accepts a value from 0.0 to 1.0. The value 0.0 represents the maximum compression (or lowest quality) while 1.0 represents the least compression (or best quality). The default is 0.6. You can additionally resize the image with the width and height options to reduce the file size even further.

Does the plugin preserve EXIF metadata?

No, the EXIF data of the image is lost during compression. If you need the metadata, read it before compressing the image and store it separately.

What does compressImage return on each platform?

On Android and iOS, the result contains the path of the compressed file. On Web, the result contains a Blob instance instead. Take this into account if you share code across platforms, for example when uploading the compressed image to a server.

Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

Related Plugins

• File Picker: Let the user select the images to compress from the file system or gallery.
• Photo Manipulator: Headless image transforms like crop, resize, rotate, flip and format conversion.
• Zip: Zip and unzip files and directories with support for encryption.

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

Breaking Changes

See BREAKING.md.

License

See LICENSE.