# image-meta

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![Codecov][codecov-src]][codecov-href]
[![bundle][bundle-src]][bundle-href]

Detect image type and size using pure JavaScript. It has no dependencies and works in Node.js, browsers and other runtimes.

## Usage

```ts
import { imageMeta } from "image-meta";

const res = await fetch(url);
const data = new Uint8Array(await res.arrayBuffer());

const meta = imageMeta(data);
// => { type: "png", width: 123, height: 456 }
```

In Node.js, a `Buffer` works as input because it is a `Uint8Array`:

```ts
import { readFile } from "node:fs/promises";
import { imageMeta } from "image-meta";

const meta = imageMeta(await readFile("./image.jpg"));
```

The type is detected from the file contents, not the file extension.

### Result

```ts
type ImageMeta = {
  type?: string; // detected format, e.g. "png"
  width: number; // of the largest image when there are several
  height: number;
  orientation?: number; // EXIF orientation (jpg)
  images?: Omit<ImageMeta, "images">[]; // all embedded images (ico, cur, icns)
  animated?: boolean; // animation or image sequence (gif, png, webp, avif, heic, jxl)
  pages?: number; // number of frames or pages (gif, png, webp, tiff)
};
```

### Animation and pages

`animated` and `pages` are read from the headers without decoding the image, and are left `undefined` when they can't be found cheaply (for example in a truncated file). A single frame is not reported as animated. For tiff, every directory counts as a page, including thumbnails and reduced-resolution images (e.g. in camera raw files).

| Format      | `animated`                                          | `pages`                 |
| ----------- | --------------------------------------------------- | ----------------------- |
| gif         | more than one frame                                 | number of frames        |
| png (APNG)  | `acTL` chunk before `IDAT`                          | `acTL` frame count      |
| webp        | `VP8X` animation flag                               | number of `ANMF` chunks |
| avif / heic | sequence brand (`avis`, `msf1`, …) and a `moov` box | -                       |
| jxl         | `have_animation` in the image metadata              | -                       |
| tiff        | -                                                   | length of the IFD chain |

> [!WARNING]
> These values are **best-effort hints**, useful for UX and processing decisions (keeping an animation when converting, skipping a step for single-frame images, showing a frame count). They are **not** reliable for security decisions such as size or resource limits: image-meta parses headers on its own, so for malformed or crafted files its answer can differ from what a decoder will do. Ask the decoder that will process the file when you need a guarantee.

### Error handling

`imageMeta` throws an error if the input is not a `Uint8Array`, the format is unsupported, or the data is invalid. Wrap calls that take untrusted input in `try/catch`:

```ts
try {
  const meta = imageMeta(data);
} catch {
  // Not a supported image
}
```

## Supported formats

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

## Development

- Clone this repository
- Install the latest LTS version of [Node.js](https://nodejs.org/en/)
- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
- Install dependencies using `pnpm install`
- Run interactive tests using `pnpm dev`

See [AGENTS.md](./AGENTS.md) for the project layout and how to add a new format.

## License

Made with 💛

🔀 Based on [image-size](https://github.com/image-size/image-size) by [Aditya Yadav](https://github.com/netroy) and [contributors](https://github.com/image-size/image-size/graphs/contributors).

Published under [MIT License](./LICENSE).

<!-- Badges -->

[npm-version-src]: https://img.shields.io/npm/v/image-meta?style=flat&colorA=18181B&colorB=F0DB4F
[npm-version-href]: https://npmjs.com/package/image-meta
[npm-downloads-src]: https://img.shields.io/npm/dm/image-meta?style=flat&colorA=18181B&colorB=F0DB4F
[npm-downloads-href]: https://npmjs.com/package/image-meta
[codecov-src]: https://img.shields.io/codecov/c/gh/unjs/image-meta/main?style=flat&colorA=18181B&colorB=F0DB4F
[codecov-href]: https://codecov.io/gh/unjs/image-meta
[bundle-src]: https://img.shields.io/bundlephobia/minzip/image-meta?style=flat&colorA=18181B&colorB=F0DB4F
[bundle-href]: https://bundlephobia.com/result?p=image-meta