Capacitor Photo Manipulator Plugin¶

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

Deliver Live Updates to your Capacitor app with Capawesome Cloud

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(...)¶

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¶

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.

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.

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.