image-dimensions
A lightweight JavaScript library to get image dimensions (width, height, type) from streams or data with minimal reads.
What is image-dimensions?
image-dimensions is a JavaScript library that extracts width, height, and format type from image files without loading the entire image. It solves the problem of efficiently obtaining image metadata by reading only the necessary bytes from streams or in-memory data, supporting formats like JPEG, PNG, WebP, AVIF, and HEIF.
JavaScript developers working in Node.js, browsers, Bun, or Deno who need to quickly retrieve image dimensions for processing, validation, or layout calculations without full image decoding.
Developers choose image-dimensions for its zero dependencies, cross-environment compatibility, and efficient stream-based reading that minimizes data transfer and memory usage compared to heavier alternatives like image-size.
Overview
Get the dimensions of an image
Use Cases
Best For
- Extracting image metadata from network streams in browser applications
- Validating image dimensions in server-side Node.js processing pipelines
- Building lightweight image analysis tools for multiple JavaScript runtimes
- Creating CLI utilities for batch image dimension checking
- Optimizing performance in applications that handle many images by avoiding full loads
- Supporting modern formats like AVIF and HEIC in cross-platform projects
Not Ideal For
- Applications requiring support for less common image formats like TIFF, BMP, or JPEG XL
- Projects that need accurate image dimensions with EXIF or HEIF/AVIF orientation applied
- Systems where comprehensive image metadata beyond basic dimensions and format is essential
Pros & Cons
Pros
Lightweight with no external dependencies, reducing bundle size and complexity, as emphasized in the Key Features.
Works in Node.js, browsers, Bun, and Deno without environment-specific code, ensuring broad runtime support from the README.
Uses `imageDimensionsFromStream` to read only necessary bytes from streams, minimizing data transfer for network or file handling.
Handles JPEG, PNG, GIF, WebP, AVIF, and HEIF/HEIC, covering many contemporary image formats used in web development.
Cons
Does not support all image formats; for example, JPEG XL is not included, and the README states supporting all formats is a non-goal.
Returns raw pixel dimensions without applying EXIF or HEIF/AVIF rotation, which can lead to incorrect values for oriented images, as noted in the API documentation.
Lacks some features found in libraries like `image-size`, such as broader format support and orientation handling, as acknowledged in the FAQ section.
Frequently Asked Questions
Related Projects
sharpHigh performance Node.js image processing, the fastest module to resize JPEG, PNG, WebP, AVIF and TIFF images. Uses the libvips library.
jimpAn image processing library written entirely in JavaScript for Node, with zero external or native dependencies.
qrcodeqr code generator
picaResize image in browser with high quality and high speed
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.