@wordpress/vips

Helper package to interact with wasm-vips.

Installation

Install the module

npm install @wordpress/vips --save

API Reference

cancelOperations

Cancels all ongoing image operations for a given item ID.

The onProgress callbacks check for an IDs existence in this list, killing the process if it's absent.

Parameters

• id ItemId: Item ID.

Returns

• boolean Whether any operation was cancelled.

compressImage

Compresses an existing image using vips.

Parameters

• id ItemId: Item ID.
• buffer ArrayBuffer: Original file buffer.
• type string: Mime type.
• options ConvertImageOptions: Compression options.

Returns

• Promise< ArrayBuffer | ArrayBufferLike >: Compressed file data.

convertImageFormat

Converts an image to a different format using vips.

Parameters

• id ItemId: Item ID.
• buffer ArrayBuffer: Original file buffer.
• inputType string: Input mime type.
• outputType string: Output mime type.
• options ConvertImageOptions: Conversion options.

getUltraHdrInfo

Probes a JPEG to determine whether it is an UltraHDR image with an embedded gain map.

Returns dimensions and HDR headroom on success, or null if the buffer is not a valid UltraHDR JPEG (no gain map, decode failure, or unsupported format).

Parameters

• buffer ArrayBuffer: Image buffer.

Returns

• Promise< UltraHdrInfo | null >: UltraHDR info, or null when the buffer is not UltraHDR.

hasTransparency

Determines whether an image has visible transparency.

Channel presence alone is not enough: PNG encoders often retain an alpha channel even when every pixel is fully opaque, and animated GIFs declare a transparent color index for disposal-method frame compositing without ever rendering a visibly transparent pixel. This check loads the first frame (any transparency there is visible — there is no previous frame to inherit from) and samples the alpha channel for an actually-transparent pixel.

Parameters

• buffer ArrayBuffer: Original file object.

Returns

• Promise< boolean >: Whether any pixel in the image is partially or fully transparent.

resizeImage

Resizes an image using vips.

UltraHDR JPEGs are auto-detected and preserved: libvips's uhdrload* has higher priority than jpegload*, so newFromBuffer/thumbnailBuffer decode the gain map alongside the base image, and jpegsave* delegates to uhdrsave* on output when a gain map is attached.

Sub-sizes of animated images are generated from the first frame only, matching WordPress core's server-side behavior: both GD and Imagick flatten animated images when resizing, and wp_calculate_image_srcset() prevents flattened sub-sizes and the animated full-size image from mixing in a srcset. Loading all frames ([n=-1]) would re-encode a full animated GIF per sub-size, which takes tens of seconds for long animations and can produce sub-sizes larger than the original file. See https://github.com/WordPress/gutenberg/issues/80266.

Parameters

• id ItemId: Item ID.
• buffer ArrayBuffer: Original file buffer.
• type string: Mime type.
• resize ImageSizeCrop: Resize options.
• options ResizeImageOptions: Additional resize options.

Returns

• Promise< { buffer: ArrayBuffer | ArrayBufferLike; width: number; height: number; originalWidth: number; originalHeight: number; } >: Processed file data plus the old and new dimensions.

rotateImage

Rotates an image based on EXIF orientation value.

EXIF orientation values: 1 = Normal (no rotation needed) 2 = Flipped horizontally 3 = Rotated 180° 4 = Flipped vertically 5 = Rotated 90° CCW and flipped horizontally 6 = Rotated 90° CW 7 = Rotated 90° CW and flipped horizontally 8 = Rotated 90° CCW

Parameters

• id ItemId: Item ID.
• buffer ArrayBuffer: Original file buffer.
• type string: Mime type.
• orientation number: EXIF orientation value (1-8).

Returns

• Promise< { buffer: ArrayBuffer | ArrayBufferLike; width: number; height: number; } >: Rotated file data plus the new dimensions.

vipsCancelOperations

Cancels all ongoing image operations for a given item ID.

The onProgress callbacks check for an IDs existence in this list, killing the process if it's absent.

Parameters

• id ItemId: Item ID.

Returns

• boolean Whether any operation was cancelled.

vipsCompressImage

Compresses an existing image using vips.

Parameters

• id ItemId: Item ID.
• buffer ArrayBuffer: Original file buffer.
• type string: Mime type.
• options ConvertImageOptions: Compression options.

Returns

• Promise< ArrayBuffer | ArrayBufferLike >: Compressed file data.

vipsConvertImageFormat

Converts an image to a different format using vips.

Parameters

• id ItemId: Item ID.
• buffer ArrayBuffer: Original file buffer.
• inputType string: Input mime type.
• outputType string: Output mime type.
• options ConvertImageOptions: Conversion options.

vipsGetUltraHdrInfo

Probes a JPEG to determine whether it is an UltraHDR image with an embedded gain map.

Returns dimensions and HDR headroom on success, or null if the buffer is not a valid UltraHDR JPEG (no gain map, decode failure, or unsupported format).

Parameters

• buffer ArrayBuffer: Image buffer.

Returns

• Promise< UltraHdrInfo | null >: UltraHDR info, or null when the buffer is not UltraHDR.

vipsHasTransparency

Determines whether an image has visible transparency.

Channel presence alone is not enough: PNG encoders often retain an alpha channel even when every pixel is fully opaque, and animated GIFs declare a transparent color index for disposal-method frame compositing without ever rendering a visibly transparent pixel. This check loads the first frame (any transparency there is visible — there is no previous frame to inherit from) and samples the alpha channel for an actually-transparent pixel.

Parameters

• buffer ArrayBuffer: Original file object.

Returns

• Promise< boolean >: Whether any pixel in the image is partially or fully transparent.

vipsResizeImage

Resizes an image using vips.

UltraHDR JPEGs are auto-detected and preserved: libvips's uhdrload* has higher priority than jpegload*, so newFromBuffer/thumbnailBuffer decode the gain map alongside the base image, and jpegsave* delegates to uhdrsave* on output when a gain map is attached.

Sub-sizes of animated images are generated from the first frame only, matching WordPress core's server-side behavior: both GD and Imagick flatten animated images when resizing, and wp_calculate_image_srcset() prevents flattened sub-sizes and the animated full-size image from mixing in a srcset. Loading all frames ([n=-1]) would re-encode a full animated GIF per sub-size, which takes tens of seconds for long animations and can produce sub-sizes larger than the original file. See https://github.com/WordPress/gutenberg/issues/80266.

Parameters

• id ItemId: Item ID.
• buffer ArrayBuffer: Original file buffer.
• type string: Mime type.
• resize ImageSizeCrop: Resize options.
• options ResizeImageOptions: Additional resize options.

Returns

• Promise< { buffer: ArrayBuffer | ArrayBufferLike; width: number; height: number; originalWidth: number; originalHeight: number; } >: Processed file data plus the old and new dimensions.

vipsRotateImage

Rotates an image based on EXIF orientation value.

EXIF orientation values: 1 = Normal (no rotation needed) 2 = Flipped horizontally 3 = Rotated 180° 4 = Flipped vertically 5 = Rotated 90° CCW and flipped horizontally 6 = Rotated 90° CW 7 = Rotated 90° CW and flipped horizontally 8 = Rotated 90° CCW

Parameters

• id ItemId: Item ID.
• buffer ArrayBuffer: Original file buffer.
• type string: Mime type.
• orientation number: EXIF orientation value (1-8).

Returns

• Promise< { buffer: ArrayBuffer | ArrayBufferLike; width: number; height: number; } >: Rotated file data plus the new dimensions.