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.