image-meta: Detect Image Formats and Dimensions

Authorunjs

Last UpdateNovember 5, 2026

LicenseMIT

Features

Reads JPEG EXIF orientation when available.
Reports embedded image sizes for ICO, CUR, and ICNS files.
Returns the dimensions of the largest image in multi-image files.
Detects animation and frame or page counts for supported formats.

How To Use It

Installation

image-meta is an ESM-only package. Install it with npm:

npm install image-meta

Basic Usage

In a browser project using a bundler, fetch an image and pass its bytes to imageMeta():

import { imageMeta } from "image-meta";
const response = await fetch("/images/photo.png");
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const bytes = new Uint8Array(await response.arrayBuffer());
const meta = imageMeta(bytes);
console.log(meta.type, meta.width, meta.height);

Inspect a Selected File in the Browser

Your web page can import the version-pinned ESM file:

<input id="image-file" type="file" accept="image/*">
<output id="image-details"></output>
<script type="module">
  import { imageMeta } from "https://cdn.jsdelivr.net/npm/image-meta/dist/index.mjs";
  const input = document.querySelector("#image-file");
  const output = document.querySelector("#image-details");
  input.addEventListener("change", async () => {
    const file = input.files?.[0];
    if (!file) {
      output.textContent = "";
      return;
    }
    try {
      const bytes = new Uint8Array(await file.arrayBuffer());
      const meta = imageMeta(bytes);
      output.textContent = `${meta.type}: ${meta.width} x ${meta.height}`;
    } catch {
      output.textContent = "Unsupported or invalid image";
    }
  });
</script>

Read a Local Image in Node.js

import { readFile } from "node:fs/promises";
import { imageMeta } from "image-meta";
const meta = imageMeta(await readFile("./photo.jpg"));
console.log(meta.width, meta.height, meta.orientation);

Public API

imageMeta(input: Uint8Array): ImageMeta returns image metadata synchronously. The input parameter accepts a Uint8Array or a Node.js Buffer.

The function throws when the input type is invalid, the format is unsupported, or required metadata is missing or corrupt.

The exported ImageMeta type defines these properties:

Property	Description
`width: number`	Image width. For multi-image files, the largest image by pixel area determines the reported dimensions.
`height: number`	Image height, from the image used for `width`.
`type?: string`	Detected format, such as `png` or `jpg`.
`orientation?: number`	JPEG EXIF orientation when present.
`images?: Omit<ImageMeta, "images">[]`	Metadata for embedded images in ICO, CUR, and ICNS files.
`animated?: boolean`	Animation or image-sequence indicator, when available. Single-frame images report `false` when the status can be determined.
`pages?: number`	Frame or page count for GIF, PNG/APNG, WebP, and TIFF, when available.

Supported Image Formats

avif, bmp, cur, dds, gif, heic, icns, ico, j2c, jp2, jpg, jxl, ktx, png, pnm, psd, svg, tga, tiff, webp.

Animation and Page Detection

The animated and pages values are read from file headers and can be undefined for incomplete files.

Format	Detection behavior
GIF	`animated` is `true` for multiple frames; `pages` counts the frames.
PNG / APNG	APNG uses the `acTL` frame count; a static PNG reports one page when its `IDAT` chunk is found.
WebP	A `VP8X` animation flag identifies animation; `pages` counts `ANMF` frames when available.
AVIF / HEIC	Sequence brands and a `moov` box indicate animation; no frame count is returned.
JPEG XL	Image metadata can indicate animation; no frame count is returned.
TIFF	`pages` counts image file directories, including thumbnails and reduced-resolution images.