0
# Image Size
1

2
Image Size is a fast, lightweight NodeJS package that extracts dimensions from image files and buffers without loading the entire image into memory. It provides zero-dependency image dimension detection for over 20 image formats with minimal memory footprint.
3

4
## Package Information
5

6
- **Package Name**: image-size
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install image-size`
10

11
## Core Imports
12

13
```typescript
14
import imageSize, { disableTypes, types } from "image-size";
15
// or named imports only
16
import { imageSize, disableTypes, types } from "image-size";
17
import { imageSizeFromFile, setConcurrency } from "image-size/fromFile";
18
```
19

20
For CommonJS:
21

22
```javascript
23
const imageSize = require("image-size"); // default export
24
// or destructured
25
const { imageSize, disableTypes, types } = require("image-size");
26
const { imageSizeFromFile, setConcurrency } = require("image-size/fromFile");
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { imageSize } from "image-size";
33
import { imageSizeFromFile } from "image-size/fromFile";
34
import { readFileSync } from "node:fs";
35

36
// From a buffer (synchronous)
37
const buffer = readFileSync("photo.jpg");
38
const dimensions = imageSize(buffer);
39
console.log(dimensions.width, dimensions.height); // 1920 1080
40

41
// From a file (asynchronous - recommended)
42
const fileDimensions = await imageSizeFromFile("photo.jpg");
43
console.log(fileDimensions.width, fileDimensions.height); // 1920 1080
44

45
// Access all available sizes for multi-size formats (ICO, CUR, HEIF)
46
const { images } = await imageSizeFromFile("icon.ico");
47
images?.forEach(img => console.log(`${img.width}x${img.height}`));
48
```
49

50
## Architecture
51

52
Image Size is built around several key components:
53

54
- **Format Detection**: Automatic image format detection using header bytes for efficient processing
55
- **Type Handlers**: Individual handler modules for each supported format (20+ formats)
56
- **Buffer Processing**: Direct Uint8Array processing for maximum performance and streaming support
57
- **File Processing**: Asynchronous file operations with configurable concurrency limits
58
- **Multi-size Support**: Handles formats containing multiple image sizes (ICO, CUR, HEIF)
59

60
## Supported Formats
61

62
BMP, CUR, DDS, GIF, HEIC (HEIF, AVCI, AVIF), ICNS, ICO, J2C, JPEG-2000 (JP2), JPEG, JPEG-XL, KTX (1 and 2), PNG, PNM (PAM, PBM, PFM, PGM, PPM), PSD, SVG, TGA, TIFF, WebP
63

64
## Capabilities
65

66
### Buffer Processing
67

68
Synchronous dimension extraction from image buffers and Uint8Array data. Perfect for streams, network requests, or when you already have image data in memory.
69

70
```typescript { .api }
71
function imageSize(input: Uint8Array): ISizeCalculationResult;
72

73
function disableTypes(types: imageType[]): void;
74

75
const types: imageType[];
76
```
77

78
[Buffer Processing](./buffer-processing.md)
79

80
### File Processing
81

82
Asynchronous dimension extraction directly from image files with configurable concurrency control. Recommended for local file operations.
83

84
```typescript { .api }
85
function imageSizeFromFile(filePath: string): Promise<ISizeCalculationResult>;
86

87
function setConcurrency(c: number): void;
88
```
89

90
[File Processing](./file-processing.md)
91

92
## Types
93

94
```typescript { .api }
95
interface ISizeCalculationResult {
96
  width: number;
97
  height: number;
98
  orientation?: number;
99
  type?: string;
100
  images?: ISize[];
101
}
102

103
interface ISize {
104
  width: number;
105
  height: number;
106
  orientation?: number;
107
  type?: string;
108
}
109

110
type imageType = 'bmp' | 'cur' | 'dds' | 'gif' | 'heif' | 'icns' | 'ico' | 'j2c' | 'jp2' | 'jpg' | 'jxl' | 'jxl-stream' | 'ktx' | 'png' | 'pnm' | 'psd' | 'svg' | 'tga' | 'tiff' | 'webp';
111

112
// Note: imageType represents format detection values. The result.type in ISizeCalculationResult 
113
// may contain more specific format strings (e.g., 'avif', 'heic' when imageType is 'heif')
114
```
115

116
## Command Line Interface
117

118
The package includes a CLI tool for quick image dimension inspection:
119

120
```bash
121
# Using npx (recommended)
122
npx image-size photo.jpg icon.png favicon.ico
123

124
# Global installation
125
npm install -g image-size
126
image-size *.jpg
127

128
# Example output:
129
# 1920x1080 - photo.jpg (jpg)
130
# 256x256 - icon.png (png)
131
# 16x16 - favicon.ico (ico)
132
# 32x32 - favicon.ico (ico)
133
```