@wix/image-kit

Image Kit

Standard library for generating canonical URL's for optimally consuming images at Wix.

Features

• Maintaining pixel perfect images
• Ensuring minimum download latency, maximum performance and maximum quality
• Optimizing images for Retina displays
• Fetching .webp images where applicable
• Handling image sharpening when needed
• Optimizing image upscaling (Wix machine learning) when needed

Example

import { sdk } from '@wix/image-kit';

const img = new Image();

img.src = sdk.getScaleToFillImageUrl('some-image.jpg', 1200, 800, 640, 480, { quality: 90 });

Installation

You have 2 options:

Install package

In public (as open-source, dist only)

You can install the package via npm/yarn

> npm install -s @wix/image-sdk

or:

> yarn add @wix/image-sdk

At Wix (with source)

You can install the package via npm/yarn

> npm install -s @wix/image-kit --registry http://npm.dev.wixpress.com/

or:

> yarn add @wix/image-kit --registry http://npm.dev.wixpress.com/

API

Method	Description
getScaleToFitImageURL()	Scales the designated image to fit in the given target width and height while retaining the original proportions.
getScaleToFillImageURL()	Scales the designated image with the exact given target width and height while retaining the original proportions. If the required proportions are different than the original, the image may be cropped to fill the provided width and height, so that only part of the original image might be visible. The position pointing to the place from which to crop the image, if needed, is set by default to the vertical and horizontal center of the image or set to the focalPoint x,y values if presented.
getCropImageURL()	Crops the designated image based on the supplied coordinates, starting at the x, y pixel coordinates, along with the width and height options. The image might be scaled according to the target dimensions.

Methods

getScaleToFitImageUrl

getScaleToFillImageUrl(
    relativeUrl,
    sourceWidth,
    sourceHeight,
    targetWidth,
    targetHeight,
    options
)

arguments

name	description	type
relativeUrl	the original image uri	string
sourceWidth	the original image width	number
sourceHeight	the original image height	number
targetWidth	target container width	number
targetHeight	target container height	number
options	additional image settings [optional]	object

options

{
   filters: {
      blur: 15
   },
   unsharpMask: {
      amount: 0.66,
      radius: 1.0,
      threshold: 0.01
   },
   name: 'hello kitty',
   quality: 80,
   upscaleMethod: 'classic',
   watermark: '3856-9876-76890-xzxz',
   isSEOBot: true,
   autoEncode: true,
}

key	valid values	default	type
filters.blur	0-100	-	number (%)
unsharpMask.amount	0-10	0.66	float
unsharpMask.radius	0.1-500	1.0	float
unsharpMask.amount	0-255	0.01	float
name	any string	''	string
quality	5-90	80	number
upscaleMethod	'auto', 'classic', 'super'	'auto'	string
watermark	watermark manifest id	-	string
isSEOBot	true or false	false	boolean
autoEncode	true or false	true	boolean
encoding	'AVIF', 'PAVIF', undefined	undefined	string
hasAnimation	true, false, undefined	false	boolean
allowAnimatedTransform	true, false, undefined	undefined	boolean
allowGIFFullTransformation	true, false, undefined	undefined	boolean
allowWebpAvifTransforms	true, false, undefined	undefined	boolean

Note on animated images:

• allowAnimatedTransform: Controls whether animated images (WebP, AVIF, GIF) can be transformed. Used primarily in placeholder flow to enable poster generation (first frame). Defaults to true in placeholder flow unless explicitly set to false.
• allowGIFFullTransformation: Controls whether GIFs can be fully transformed (with animation preserved) in non-placeholder flows. When true, uses anm_-1 flag to preserve full animation. Only applies to GIF images in non-placeholder flows.

Note on WebP and AVIF spatial transforms:

• allowWebpAvifTransforms: When true, transform URLs for WebP and AVIF may include alignment, focal point, and crop. When false or omitted, those are stripped for WebP/AVIF (legacy default) so older pipelines do not send spatial parameters for these formats.

returns

returns image url [string]

getScaleToFillImageURL

getScaleToFillImageUrl(
    relativeUrl,
    sourceWidth,
    sourceHeight,
    targetWidth,
    targetHeight,
    options
)

arguments

name	description	type
relativeUrl	the original image uri	string
sourceWidth	the original image width	number
sourceHeight	the original image height	number
targetWidth	target container width	number
targetHeight	target container height	number
options	additional image settings [optional]	object

options

{
   filters: {
      blur: 15
   },
   unsharpMask: {
      amount: 0.66,
      radius: 1.0,
      threshold: 0.01
   },
   focalPoint: {
      x: 50,
      y: 50
   },
   name: 'hello kitty',
   quality: 80,
   upscaleMethod: 'classic'
   watermark: '3856-9876-76890-xzxz',
   isSEOBot: true,
   autoEncode: true
}

key	valid values	default	type
filters.blur	0-100	-	number (%)
unsharpMask.amount	0-10	0.66	float
unsharpMask.radius	0.1-500	1.0	float
unsharpMask.amount	0-255	0.01	float
focalPoint.x	0-100	-	number (%)
focalPoint.y	0-100	-	number (%)
name	any string	''	string
quality	5-90	80	number
upscaleMethod	'auto', 'classic', 'super'	'auto'	string
watermark	watermark manifest id	-	string
isSEOBot	true or false	false	boolean
autoEncode	true or false	true	boolean
encoding	'AVIF', 'PAVIF', undefined	undefined	string
hasAnimation	true, false, undefined	false	boolean
allowAnimatedTransform	true, false, undefined	undefined	boolean
allowGIFFullTransformation	true, false, undefined	undefined	boolean
allowWebpAvifTransforms	true, false, undefined	undefined	boolean

Note on animated images:

• allowAnimatedTransform: Controls whether animated images (WebP, AVIF, GIF) can be transformed. Used primarily in placeholder flow to enable poster generation (first frame). Defaults to true in placeholder flow unless explicitly set to false.
• allowGIFFullTransformation: Controls whether GIFs can be fully transformed (with animation preserved) in non-placeholder flows. When true, uses anm_-1 flag to preserve full animation. Only applies to GIF images in non-placeholder flows.

Note on WebP and AVIF spatial transforms:

• allowWebpAvifTransforms: When true, transform URLs for WebP and AVIF may include alignment, focal point, and crop. When false or omitted, those are stripped for WebP/AVIF (legacy default) so older pipelines do not send spatial parameters for these formats.

returns

returns image url [string]

getCropImageURL

getCropImageUrl(
    relativeUrl,
    sourceWidth,
    sourceHeight,
    cropX,
    cropY,
    cropWidth,
    cropHeight,
    targetWidth,
    targetHeight,
    options
)

arguments

name	description	type
relativeUrl	the original image uri	string
sourceWidth	the original image width	number
sourceHeight	the original image height	number
cropX	the X pixel coordinate to start cropping from	number
cropY	the Y pixel coordinate to start cropping from	number
cropWidth	the width constraint	number
cropHeight	the height constraint	number
targetWidth	target container width	number
targetHeight	target container height	number
options	additional image settings [optional]	object

options

{
   filters: {
      blur: 15
   },
   unsharpMask: {
      amount: 0.66,
      radius: 1.0,
      threshold: 0.01
   },
   focalPoint: {
      x: 50,
      y: 50
   },
   name: 'hello kitty',
   quality: 80,
   upscaleMethod: 'classic',
   watermark: '3856-9876-76890-xzxz',
   isSEOBot: true,
   autoncode: true
}

key	valid values	default	type
filters.blur	0-100	-	number (%)
unsharpMask.amount	0-10	0.66	float
unsharpMask.radius	0.1-500	1.0	float
unsharpMask.amount	0-255	0.01	float
name	any string	''	string
quality	5-90	80	number
upscaleMethod	'auto', 'classic', 'super'	'auto'	string
watermark	watermark manifest id	-	string
isSEOBot	true or false	false	boolean
hasAnimation	true, false, undefined	false	boolean
allowAnimatedTransform	true, false, undefined	undefined	boolean
allowGIFFullTransformation	true, false, undefined	undefined	boolean
allowWebpAvifTransforms	true, false, undefined	undefined	boolean

Note on animated images:

• allowAnimatedTransform: Controls whether animated images (WebP, AVIF, GIF) can be transformed. Used primarily in placeholder flow to enable poster generation (first frame). Defaults to true in placeholder flow unless explicitly set to false.
• allowGIFFullTransformation: Controls whether GIFs can be fully transformed (with animation preserved) in non-placeholder flows. When true, uses anm_-1 flag to preserve full animation. Only applies to GIF images in non-placeholder flows.

Note on WebP and AVIF spatial transforms:

• allowWebpAvifTransforms: When true, transform URLs for WebP and AVIF may include alignment, focal point, and crop. When false or omitted, those are stripped for WebP/AVIF (legacy default) so older pipelines do not send spatial parameters for these formats.

returns

returns image url [string]