Capacitor Photo Manipulator Plugin

Capacitor plugin for headless image transforms like crop, resize, rotate, flip and format conversion, including HEIC to JPEG.

Features

• 🖼️ Headless Transforms: Crop, resize, rotate and flip images from code, without any UI.
• 🔄 HEIC to JPEG: Convert HEIC and AVIF photos to JPEG, PNG or WebP with the native platform decoders. No WASM blobs, no WebView memory spikes.
• 📐 Upright Output: The EXIF orientation is applied during decoding so the output is always upright.
• 🧠 Memory Efficient: Bounds-aware downsampled decoding, so full-resolution bitmaps are never loaded when resizing.
• 🕵️ Privacy Friendly: All metadata (e.g. EXIF, GPS) is stripped from the output by re-encoding.
• 📂 File Output: Results are written to files, so even large images don't exhaust memory.
• ℹ️ Image Info: Read the dimensions and format of an image without decoding the pixel data.
• 🤝 Compatibility: Works alongside the Photo Editor, Exif and File Compressor plugins.
• 🔒 App Store safe: Uses only official platform APIs.
• 📦 CocoaPods & SPM: Supports CocoaPods and Swift Package Manager for iOS.
• 🔁 Up-to-date: Always supports the latest Capacitor version.

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

Use Cases

The Photo Manipulator plugin is typically used whenever an app needs to process images from code, without any UI, for example:

• HEIC to JPEG conversion: Convert photos taken on an iPhone to JPEG before uploading them, so servers and browsers can display them.
• Thumbnail generation: Crop and resize images to small previews with memory-efficient downsampled decoding.
• Upload size reduction: Resize images and re-encode them with a lower quality before uploading them to a server.
• Privacy-safe sharing: Share images without metadata, since all metadata (e.g. EXIF, GPS) is stripped from the output by re-encoding.
• Orientation fixes: Produce upright images, since the EXIF orientation is applied during decoding.

Compatibility

| Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.x.x | >=8.x.x | Active support |

Installation

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/capacitor-photo-manipulator` 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/capacitor-photo-manipulator
npx cap sync

Android

Variables

This plugin will use the following project variables (defined in your app's variables.gradle file):

• $androidxExifInterfaceVersion version of androidx.exifinterface:exifinterface (default: 1.4.1)

iOS

On iOS, this plugin uses the Image I/O and Core Graphics frameworks. No additional configuration is required.

Web

This plugin provides a partial web implementation based on the Canvas API. HEIC and AVIF images can not be decoded by most browsers, which is exactly why the native implementations exist (see Format Support).

Configuration

No configuration required for this plugin.

Usage

The following examples show how to convert an image to another format, create a thumbnail, and read the dimensions and format of an image.

The transformed image is written to a new file in the cache directory and deleted on the next app launch. Move it to a permanent location if you want to keep it, for example with the rename(...) method of the Filesystem plugin.

Convert a HEIC image to JPEG

Use the format option of the transform(...) method to convert an image to another format, for example a HEIC photo taken on an iPhone to JPEG. The quality option controls the compression of the output file:

import { PhotoManipulator, ImageFormat } from '@capawesome/capacitor-photo-manipulator';

const convertHeicToJpeg = async () => {
  // Convert an HEIC photo (e.g. taken on an iPhone) to JPEG
  const { path } = await PhotoManipulator.transform({
    path: 'file:///var/mobile/.../photo.heic',
    format: ImageFormat.Jpeg,
    quality: 0.9,
  });
  return path;
};

Create a thumbnail

Combine the crop, resize, rotate and flip options in a single call. The operations are always applied in the fixed order crop → resize → rotate → flip:

import { PhotoManipulator } from '@capawesome/capacitor-photo-manipulator';

const createThumbnail = async () => {
  // Crop, resize, rotate and flip in one call
  const { path, width, height } = await PhotoManipulator.transform({
    path: 'file:///var/mobile/.../photo.jpeg',
    crop: { x: 100, y: 100, width: 1080, height: 1080 },
    resize: { width: 256 },
    rotate: 90,
    flipHorizontal: true,
  });
  return { path, width, height };
};

Read the dimensions and format of an image

Use the getInfo(...) method to read the dimensions and format of an image without decoding the pixel data where possible:

import { PhotoManipulator } from '@capawesome/capacitor-photo-manipulator';

const getInfo = async () => {
  const { width, height, format } = await PhotoManipulator.getInfo({
    path: 'file:///var/mobile/.../photo.heic',
  });
  return { width, height, format };
};

API

• getInfo(...)
• transform(...)
• Interfaces
• Enums

getInfo(...)

getInfo(options: GetInfoOptions) => Promise<GetInfoResult>

Get the dimensions and format of an image without decoding the pixel data where possible.

| Param | Type | | ------------- | --------------------------------------------------------- | | options | GetInfoOptions |

Returns: Promise<GetInfoResult>

Since: 0.1.0

transform(...)

transform(options: TransformOptions) => Promise<TransformResult>

Apply one or more transformations to an image and write the result to a new file.

The operations are always applied in the following fixed order: crop → resize → rotate → flip. Chain multiple calls if you need a different order.

The EXIF orientation of the source image is applied during decoding so that the output is always upright. All other metadata (e.g. EXIF, GPS) is stripped by re-encoding.

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | TransformOptions |

Returns: Promise<TransformResult>

Since: 0.1.0

Interfaces

GetInfoResult

| Prop | Type | Description | Since | | ------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | | format | string | null | The format of the image or null if the format could not be determined. The value is provided by the platform decoder and may differ slightly between platforms for the same file (e.g. heic on iOS and the web but heif on Android). | 0.1.0 | | height | number | The height of the image in pixels after the EXIF orientation has been applied. | 0.1.0 | | width | number | The width of the image in pixels after the EXIF orientation has been applied. | 0.1.0 |

GetInfoOptions

| Prop | Type | Description | Since | | ---------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | path | string | The path of the image file. On Android and iOS, only local file paths and file:// URIs are supported. On the web, any fetchable URL (e.g. https://, blob:, data:) is supported. | 0.1.0 |

TransformResult

| Prop | Type | Description | Since | | ------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | height | number | The height of the transformed image in pixels. | 0.1.0 | | path | string | The path of the transformed image file. On Android and iOS, the file is stored in the cache directory and deleted on the next app launch. Move it to a permanent location if you want to keep it. On the web, the path is an object URL. | 0.1.0 | | width | number | The width of the transformed image in pixels. | 0.1.0 |

TransformOptions

| Prop | Type | Description | Default | Since | | -------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ----- | | crop | CropOptions | The region of the source image to crop to, in source pixels. The region must be within the bounds of the source image. | | 0.1.0 | | flipHorizontal | boolean | Whether or not to flip the image horizontally. | false | 0.1.0 | | flipVertical | boolean | Whether or not to flip the image vertically. | false | 0.1.0 | | format | ImageFormat | The format of the output file. On iOS, ImageFormat.Webp is not supported and rejects with the UNSUPPORTED_FORMAT error code. | ImageFormat.Jpeg | 0.1.0 | | path | string | The path of the image file to transform. On Android and iOS, only local file paths and file:// URIs are supported. On the web, any fetchable URL (e.g. https://, blob:, data:) is supported. | | 0.1.0 | | quality | number | The quality of the output file between 0 and 1. Only applied when format is ImageFormat.Jpeg or ImageFormat.Webp. | 0.9 | 0.1.0 | | resize | ResizeOptions | The target size to resize the image to, in pixels. If only one of width and height is provided, the aspect ratio is preserved. The resize is applied after the crop. | | 0.1.0 | | rotate | number | The clockwise angle to rotate the image by, in degrees. Must be 90, 180 or 270. | 0 | 0.1.0 |

CropOptions

| Prop | Type | Description | Since | | ------------ | ------------------- | ---------------------------------------------------------------------------------------------------- | ----- | | height | number | The height of the crop region in pixels. | 0.1.0 | | width | number | The width of the crop region in pixels. | 0.1.0 | | x | number | The horizontal offset of the crop region in pixels, measured from the left edge of the source image. | 0.1.0 | | y | number | The vertical offset of the crop region in pixels, measured from the top edge of the source image. | 0.1.0 |

ResizeOptions

| Prop | Type | Description | Since | | ------------ | ------------------- | ------------------------------------------------------------------------------------------------------------ | ----- | | height | number | The target height in pixels. If only one of width and height is provided, the aspect ratio is preserved. | 0.1.0 | | width | number | The target width in pixels. If only one of width and height is provided, the aspect ratio is preserved. | 0.1.0 |

Enums

ImageFormat

| Members | Value | Description | Since | | ---------- | ------------------- | ------------------------------------------------------- | ----- | | Jpeg | 'JPEG' | JPEG (image/jpeg). | 0.1.0 | | Png | 'PNG' | PNG (image/png). | 0.1.0 | | Webp | 'WEBP' | WebP (image/webp). Only available on Android and Web. | 0.1.0 |

Format Support

The formats an image can be decoded from and encoded to depend on the platform:

Input (Decode)

| Format | Android | iOS | Web | | --------- | ---------------- | ------------ | ----------------- | | JPEG | ✅ | ✅ | ✅ | | PNG | ✅ | ✅ | ✅ | | WebP | ✅ | ✅ | ✅ | | GIF | ✅ | ✅ | ✅ | | BMP | ✅ | ✅ | ✅ | | HEIC/HEIF | ✅ (Android 9+) | ✅ | ❌ | | AVIF | ✅ (Android 12+) | ✅ (iOS 16+) | Browser-dependent |

Output (Encode)

| Format | Android | iOS | Web | | ------ | ------- | --- | ----------------- | | JPEG | ✅ | ✅ | ✅ | | PNG | ✅ | ✅ | ✅ | | WebP | ✅ | ❌ | Browser-dependent |

If an image can not be decoded or encoded on the current platform, the call is rejected with the UNSUPPORTED_FORMAT error code so you can fall back gracefully.

Memory

This plugin is designed to keep the memory footprint low, even for very large images:

• When a resize target is provided, the image is decoded downsampled (using inSampleSize on Android and kCGImageSourceThumbnailMaxPixelSize on iOS) so the full-resolution bitmap is never loaded into memory.
• Transforms are processed one at a time on a background queue.
• The result is written to a file instead of being returned as base64 data.

For the smallest possible memory footprint, always provide a resize target if you don't need the full resolution.

Metadata

The EXIF orientation of the source image is applied during decoding so that the output is always upright. All other metadata (e.g. EXIF, GPS) is stripped by re-encoding. Use the Exif plugin if you want to read the metadata of the source image and write it back to the transformed image.

FAQ

How is this plugin different from other similar plugins?

It performs headless image transforms — crop, resize, rotate, flip and format conversion, including HEIC and AVIF to JPEG, PNG or WebP — using the native platform decoders, with no UI and no WebView memory spikes. It decodes bounds-aware and downsampled so full-resolution bitmaps are never loaded when resizing, applies the EXIF orientation for always-upright output, writes results to files, and strips metadata on re-encode for privacy-safe sharing. It works on Android, iOS and the Web, uses only official platform APIs, and is fully typed and kept current with the latest Capacitor version.

In which order are the transformations applied?

The operations are always applied in the following fixed order: crop → resize → rotate → flip. If you need a different order, chain multiple transform(...) calls, passing the output path of one call as the input path of the next.

Why does the transformed image disappear after an app restart?

On Android and iOS, the transformed image is written to a new file in the cache directory and deleted on the next app launch. Move it to a permanent location if you want to keep it, for example with the rename(...) method of the official Filesystem plugin.

Does the plugin preserve the EXIF metadata of the source image?

No, the EXIF orientation is applied during decoding so that the output is always upright, and all other metadata (e.g. EXIF, GPS) is stripped from the output by re-encoding. This is privacy-friendly by default. If you want to keep the metadata, use the Exif plugin to read it from the source image and write it back to the transformed image.

Why does converting to WebP fail on iOS?

On iOS, ImageFormat.Webp is not supported as an output format and the call rejects with the UNSUPPORTED_FORMAT error code. WebP output is only available on Android and the Web. Use ImageFormat.Jpeg or ImageFormat.Png as a cross-platform alternative.

Why can't I convert HEIC or AVIF images on the Web?

The web implementation is based on the Canvas API, and most browsers cannot decode HEIC and AVIF images. This is exactly why the native implementations exist: on Android (9+ for HEIC/HEIF, 12+ for AVIF) and iOS (16+ for AVIF), the plugin uses the native platform decoders. See the Format Support section for the complete overview.

How does the plugin handle very large images?

The plugin is designed to keep the memory footprint low. When a resize target is provided, the image is decoded downsampled so the full-resolution bitmap is never loaded into memory, transforms are processed one at a time on a background queue, and the result is written to a file instead of being returned as base64 data. For the smallest possible memory footprint, always provide a resize target if you don't need the full resolution.

Related Plugins

• Photo Editor: Let the user edit a photo in an installed photo editing app.
• Exif: Read, write and remove EXIF metadata from image files.
• File Compressor: Compress files with support for image formats like PNG, JPEG, and WebP.
• File Picker: Let the user select the images to transform from the gallery or file system.

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.

License

See LICENSE.