heic2any

When using HEIC2ANY, keep the following constraints in mind:

• Environment: This library is specifically for the browser environment. It requires a browser-like environment with the existence of the DOM and window object. It will not work in a Node.js environment.
• Purpose: The library is optimized for viewing purposes. It is designed to create a browser-consumable version of an HEIC file quickly.
• Metadata: The library does not copy metadata from the original HEIC file to the output (JPEG, GIF, or PNG). If your use case requires preserving metadata for storage, you should use a server-side tool instead.

Since heic2any returns a Promise, you should handle errors using a .catch() block. When an error occurs, the rejected object contains a code (representing the error class) and a message (providing specific details about the failure).

// fetching the heic image
fetch("./my-image.heic")
	.then((res) => res.blob())
	.then((blob) => heic2any({ blob }))
	.then((conversionResult) => {
		var url = URL.createObjectURL(conversionResult);
		document.getElementById("my-image").innerHTML = `<img src="${url}">`;
	})
	.catch((errorObject) => {
		console.log(errorObject);
	});

If you are using a module bundler, import the library using ES modules or CommonJS syntax.

import heic2any from "heic2any";
// or
const heic2any = require("heic2any");

You can install heic2any using npm or yarn if you are using a module bundler. If you are not using a module bundler, you can include the library directly via a <script> tag pointing to the distribution file.

# npm
npm install heic2any

# yarn
yarn add heic2any

<!-- No module bundler: include via script tag -->
<script src="./dist/heic2any.js"></script>

Two options are specific to certain output formats:

1. quality: A number between 0 and 1 (default 0.92). This is only applied when toType is set to image/jpeg.
2. gifInterval: A number representing seconds (default 0.4). This controls the frame delay between images and is only applied when toType is set to image/gif.

// Example: Creating an animated GIF with a custom interval
heic2any({
  toType: 'image/gif',
  gifInterval: 0.2
});

The toType option determines the MIME type of the resulting image.

• Use image/png for maximum quality (default).
• Use image/jpeg to reduce file size by adjusting the quality parameter.
• Use image/gif to convert animated HEIC sets into animated GIFs.

Important: When toType is set to image/gif, all other options (including multiple and quality) are ignored, except for gifInterval.

// Example: Converting to JPEG with specific quality
heic2any({
  toType: 'image/jpeg',
  quality: 0.7
});

Developers using HEIC2ANY should be aware of the following known issues:

1. Metadata Loss: The resulting file does not contain any metadata from the original file.
2. Animation Handling: While the library can convert HEIC bursts into animated GIFs, it will only capture the first shot if a HEIC animation (such as a star animation) is provided.
3. Browser Support: Support for IE11 is not currently available.
4. Environment Dependency: Requires a browser-like environment (DOM and window object).

You can specify the output format using toType and control the compression/quality using the quality option (a float value).

fetch("./my-image.heic")
	.then((res) => res.blob())
	.then((blob) =>
		heic2any({
			blob,
			toType: "image/jpeg",
			quality: 0.5, // cuts the quality and size by half
		})
	)
	.then((conversionResult) => {
		// conversionResult is a BLOB of the JPEG formatted image with low quality
	})
	.catch((e) => {
		// handle error
	});

To convert a HEIC file containing multiple images (like a burst) into an animated GIF, set toType to image/gif and use the gifInterval option to define the frame duration in seconds.

fetch("./my-image.heic")
	.then((res) => res.blob())
	.then((blob) =>
		heic2any({
			blob,
			toType: "image/gif",
			gifInterval: 0.3, // switch frames every 0.3 second
		})
	)
	.then((conversionResult) => {
		// conversionResult is a BLOB of the gif formatted image
	})
	.catch((e) => {
		// handle error
	});

Perform a basic conversion from a HEIC blob to a PNG blob by passing an object with the blob property to heic2any.

fetch("./my-image.heic")
	.then((res) => res.blob())
	.then((blob) => heic2any({ blob }))
	.then((conversionResult) => {
		// conversionResult is a BLOB of the PNG formatted image
	})
	.catch((e) => {
		// handle error
	});

Some HEIC files contain multiple images. To extract all images as individual files, set the multiple option to true. The result will be an array of BLOBs instead of a single BLOB.

fetch("./my-image.heic")
	.then((res) => res.blob())
	.then((blob) =>
		heic2any({
			blob,
			toType: "image/png",
			multiple: true,
		})
	)
	.then((conversionResult) => {
		// conversionResult is an array of BLOBs that are PNG formatted images
	})
	.catch((e) => {
		// handle error
	});