---
title: Exploring the Capacitor File Compressor API
description: "Practical guide to the Capacitor File Compressor API: compress images and files at native speed in Ionic and Capacitor apps."
date: 
  created: 2025-07-10
  updated: 2026-09-07
authors:
  - robingenz
categories:
  - Capacitor
  - Guides
  - SDKs
links:
  - Capacitor File Compressor: sdks/capacitor/file-compressor.md
faq: true
---

# Exploring the Capacitor File Compressor API

File compression matters whenever a mobile app handles image uploads, storage, or limited bandwidth. The [Capacitor File Compressor plugin](../../sdks/capacitor/file-compressor.md) from Capawesome compresses images in Ionic and Capacitor apps, reducing file sizes while keeping quality at an acceptable level. One API covers Android, iOS, and Web, so you don't write a separate compression implementation per platform.

<!-- more -->

## Installation

To install the Capacitor File Compressor plugin, please refer to the [Installation](../../sdks/capacitor/file-compressor.md/#installation) section in the plugin documentation.

## Usage

Let's explore the key features of the Capacitor File Compressor API and how to implement them effectively in your Ionic applications.

### Compressing Images

The plugin's main method is [`compressImage(...)`](../../sdks/capacitor/file-compressor.md#compressimage), which compresses an image at the quality level you choose:

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

const compressImage = async (imagePath: string) => {
  const { path } = await FileCompressor.compressImage({
    mimeType: 'image/jpeg',
    path: imagePath,
    quality: 0.7,
  });
  return path;
};
```

The `compressImage(...)` method accepts several configuration options to control the compression process, including:

- `mimeType`: The output format (`image/jpeg` or `image/webp`; iOS supports `image/jpeg` only)
- `path`: The file path of the image to compress
- `quality`: Compression quality from 0.0 (maximum compression) to 1.0 (best quality)

For more aggressive compression, you can lower the quality value:

```ts
const compressImageHeavily = async (imagePath: string) => {
  const { path } = await FileCompressor.compressImage({
    mimeType: 'image/jpeg',
    path: imagePath,
    quality: 0.3, // Higher compression, lower quality
  });
  
  return path;
};
```

You can also specify different output formats based on your needs. For example, converting PNG images to JPEG for better compression:

```ts
const convertAndCompress = async (pngPath: string) => {
  const { path } = await FileCompressor.compressImage({
    mimeType: 'image/jpeg', // Convert PNG to JPEG
    path: pngPath,
    quality: 0.8,
  });
  
  return path;
};
```

You can also resize images while compressing them by specifying the desired height and/or width:

```ts
const compressAndResizeImage = async (imagePath: string, inputFormat: string) => {
  const { path } = await FileCompressor.compressImage({
    height: 800, // Resize height to 800 pixels
    mimeType: 'image/jpeg',
    path: imagePath,
    quality: 0.7,
    width: 600, // Resize width to 600 pixels
  });
  return path;
};
```

## Best Practices

When implementing image compression with the Capacitor File Compressor API, consider these best practices:

1. **Choose appropriate quality levels**: Balance file size reduction with visual quality by testing different quality values for your specific use case. Generally, values between 0.6 and 0.8 provide good compression while maintaining acceptable quality for most applications.

2. **Handle compression errors gracefully**: Implement comprehensive error handling to manage scenarios where compression fails, such as unsupported file formats or corrupted images. Always provide fallback options or user feedback when compression cannot be completed.

3. **Consider format conversion strategically**: Convert PNG images to JPEG when transparency is not required, since JPEG usually compresses better. For images that need transparency, use `image/webp` as the output format on Android and web. On iOS the plugin only outputs JPEG, so transparency is lost there.

## FAQ

### Can I output a compressed image as PNG?

No. PNG is only supported as an input format, not as an output `mimeType`. On Android and web, you can compress to `image/jpeg` or `image/webp`; on iOS, only `image/jpeg` is supported as output. If you feed the plugin a PNG and set `mimeType: 'image/jpeg'`, it converts it to JPEG in the process. There's no way to get a compressed PNG back out.

### Does WebP output work the same on iOS as on Android?

No. WebP output is supported on Android and web, but iOS only supports `image/jpeg` as an output format. If your app needs consistent WebP output across all three platforms, iOS is the platform that won't support it — plan for a JPEG fallback there.

### What's the actual default quality if I don't set one?

`0.6`, on a `0.0` (maximum compression, lowest quality) to `1.0` (least compression, best quality) scale. If your app doesn't explicitly set `quality`, it isn't running uncompressed. It's already applying this default level.

### Does specifying `width` and `height` preserve the image's aspect ratio?

The plugin resizes to whatever width and height values you pass — it doesn't independently calculate and lock an aspect ratio for you. If you want to preserve the original proportions, you need to calculate the target `width`/`height` pair yourself based on the source image's dimensions before passing them in.

### Can I compress a `Blob` directly, or do I always need a file path?

It depends on the platform. On web, you pass a `blob`; on Android and iOS, you pass a `path` to the file instead. The two options aren't interchangeable across platforms. Code that branches on `Capacitor.getPlatform()` to supply the right one is the typical pattern for a cross-platform implementation.

## Conclusion

Start with `mimeType: 'image/jpeg'` and `quality: 0.7`, then lower the quality until the result stops looking acceptable for your use case. If you want WebP output, plan a JPEG fallback on iOS, where it isn't supported. The [Capacitor File Compressor plugin](../../sdks/capacitor/file-compressor.md) documentation lists the remaining options.

To stay updated with the latest updates, features, and news about the Capawesome, Capacitor, and Ionic ecosystem, subscribe to the [Capawesome newsletter](/newsletter/){:target="_blank"} and follow us on [X (formerly Twitter)](https://x.com/capawesomeio){:target="_blank"}.

If you have any questions or need assistance with the Capacitor File Compressor plugin, join the [Capawesome Discord server](https://discord.gg/VCXxSVjefW){:target="_blank"} or reach out to the Capawesome team.