ImageTransform

auto turns on the Image Delivery API's automatic WebP optimization for the image.

Returns: ImageTransform. The same builder, for chaining.

Validation

• There is no client-side validation. auto takes no arguments and cannot fail.

Behavior

• auto writes auto=webp. The SDK fixes the value at webp, so the method has no other setting.
• With auto=webp, the Image Delivery API serves the image as WebP to browsers that support WebP. It reads support from the Accept request header. A client whose Accept header does not list image/webp receives the image in its original format.
• The format method with Format.WEBP does not force WebP either. The API applies the same Accept header check to it.

Example

Basic usage: turn on automatic WebP optimization

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().auto();

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?auto=webp

bgColor sets the background color the Image Delivery API uses for transparent pixels and for area added by padding or a canvas.

Returns: ImageTransform. The same builder, for chaining.

Validation

• There is no client-side validation. bgColor writes an invalid hex code or an array of any length as given.
• Known issue: In 5.x, bgColor does not URL-encode the value. A leading # starts the URL fragment, so the browser sends neither the color nor any later parameter to the API. Pass a hex code without the #.
• Any rejection of the value comes from the Image Delivery API when the URL loads, not from bgColor(). A value that is not a color, for example 'zzz', fails with status 502.

Behavior

• bgColor writes bg-color=<color>. The SDK joins an array with commas.
• Pass a hex code as a string of three or six digits, for example 'ccc' or 'cccccc'.
• Pass an RGB color as an array of three numbers from 0 to 255, or an RGBA color as an array of four. The fourth number is the alpha value, which sets the transparency from 0 (fully transparent) to 1 (fully opaque). For every accepted format, refer to the Background Color section of the Image Delivery API reference.
• The API applies the color to transparent pixels of the image and to the area that the padding or canvas method adds. Without bgColor, that added area is white, or transparent when the output format supports transparency.

Example

Basic usage: set a gray background from a hex code

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().bgColor('cccccc');

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?bg-color=cccccc

Set a background from RGBA values

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().bgColor([140, 220, 123, 0.5]);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?bg-color=140,220,123,0.5

blur reduces the focus and clarity of the image.

Returns: ImageTransform. The same builder, for chaining.

Validation

• There is no client-side validation. blur writes 0, a negative number, or a value above 1000 as given.
• Passing a string is a compile error, because blurValue is a number.
• Any rejection of the value comes from the Image Delivery API when the URL loads, not from blur(). The API rejects 0, a negative number, and a value above 1000 with status 400.

Behavior

• blur writes blur=<blurValue>.
• A higher value blurs the image more.
• To increase the definition of edges instead, use the sharpen method.

Example

Basic usage: blur an image

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().blur(10);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?blur=10

brightness adjusts the brightness of the image.

Returns: ImageTransform. The same builder, for chaining.

Validation

• There is no client-side validation. brightness writes a value outside -100 to 100 as given.
• Passing a string is a compile error, because brightnessValue is a number.
• Any rejection of the value comes from the Image Delivery API when the URL loads, not from brightness(). The API rejects a value outside -100 to 100 with status 400.

Behavior

• brightness writes brightness=<brightnessValue>, keeping any decimal places, for example brightness=-35.5.
• A positive value increases the brightness, a negative value decreases it, and 0 leaves it unchanged.

Example

Basic usage: brighten an image

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().brightness(20);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?brightness=20

Darken an image by a decimal amount

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().brightness(-35.5);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?brightness=-35.5

canvas enlarges the canvas around the image to a set size, a region, an offset, or an aspect ratio.

Returns: ImageTransform. The same builder, for chaining.

Validation

• There is no client-side validation. canvas writes negative or out-of-range values as given.
• Omitting width or height is a compile error, because the type declares both properties without ?.
• canvas skips a falsy xval or yval. A position of 0 writes nothing, so xval: 0 does not appear in the URL.
• Any rejection of a value comes from the Image Delivery API when the URL loads, not from canvas().

Behavior

• canvas writes canvas=<value>. canvasBy decides the shape of the value. CanvasBy has the following four members:
  • CanvasBy.DEFAULT (default) writes canvas=<width>,<height>.
  • CanvasBy.ASPECTRATIO (aspectRatio) writes canvas=<width>:<height>.
  • CanvasBy.REGION (region) writes canvas=<width>,<height>,x<xval>,y<yval>, where xval and yval set the position of the image's top-left corner on the canvas.
  • CanvasBy.OFFSET (offset) writes canvas=<width>,<height>,offset-x<xval>,offset-y<yval>, where xval and yval offset the canvas on its X and Y axes.
• Without a position, the API centers the image on the canvas.
• CanvasBy.ASPECTRATIO needs no size. Without one, the API returns the smallest canvas of that ratio that holds the whole image. For example, 1:1 turns a 640 by 360 image into a 640 by 640 canvas.
• With REGION and OFFSET, canvas adds each of xval and yval only when you pass it.
• xval and yval have no effect with CanvasBy.DEFAULT and CanvasBy.ASPECTRATIO.
• Use the bgColor method to set the color of the added canvas area.
• Each call replaces the whole canvas value.
• For the full parameter rules, refer to the Canvas section of the Image Delivery API reference.

Example

Basic usage: place the image on a 600 by 400 canvas

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().canvas({ width: 600, height: 400 });

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?canvas=600,400

All parameters: place the image on the canvas by offset

import { CanvasBy, ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().canvas({
  width: 600,
  height: 400,
  xval: 50,
  yval: 25,
  canvasBy: CanvasBy.OFFSET,
});

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?canvas=600,400,offset-x50,offset-y25

Set the canvas by region with a white background

import { CanvasBy, ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform()
  .canvas({ width: 600, height: 400, xval: 100, yval: 150, canvasBy: CanvasBy.REGION })
  .bgColor('ffffff');

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?canvas=600,400,x100,y150&bg-color=ffffff

Extend the canvas to a 16:9 aspect ratio

import { CanvasBy, ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().canvas({ width: 16, height: 9, canvasBy: CanvasBy.ASPECTRATIO });

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?canvas=16:9

contrast adjusts the contrast of the image.

Returns: ImageTransform. The same builder, for chaining.

Validation

• There is no client-side validation. contrast writes a value outside -100 to 100 as given.
• Passing a string is a compile error, because contrastValue is a number.
• Any rejection of the value comes from the Image Delivery API when the URL loads, not from contrast(). The API rejects a value outside -100 to 100 with status 400.

Behavior

• contrast writes contrast=<contrastValue>, keeping any decimal places, for example contrast=-80.99.
• A positive value increases the contrast, a negative value decreases it, and 0 leaves it unchanged.

Example

Basic usage: increase the contrast of an image

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().contrast(30);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?contrast=30

Reduce the contrast by a decimal amount

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().contrast(-80.99);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?contrast=-80.99

crop removes pixels from the image to a set size, a region, an offset, or an aspect ratio.

Returns: ImageTransform. The same builder, for chaining.

Validation

• There is no client-side validation. crop writes negative or out-of-bounds values as given.
• Omitting width or height is a compile error, because the type declares both properties without ?.
• Known issue: In 5.x, with CropBy.REGION or CropBy.OFFSET, an omitted xval or yval writes the text undefined, for example crop=300,400,xundefined,yundefined. Pass both xval and yval.
• safe and smart have no effect with CropBy.ASPECTRATIO. crop adds them only to the comma-separated forms.
• Any rejection of a value comes from the Image Delivery API when the URL loads, not from crop().

Behavior

• crop writes crop=<value>. cropBy decides the shape of the value. CropBy has the following four members:
  • CropBy.DEFAULT (default) writes crop=<width>,<height>.
  • CropBy.ASPECTRATIO (aspectRatio) writes crop=<width>:<height>.
  • CropBy.REGION (region) writes crop=<width>,<height>,x<xval>,y<yval>, where xval and yval set the top-left corner of the crop.
  • CropBy.OFFSET (offset) writes crop=<width>,<height>,offset-x<xval>,offset-y<yval>, where xval and yval set the center point of the crop.
• safe: true appends safe, and smart: true then appends smart.
• With safe, a crop area that runs past the image edge does not return an error. The API returns the overlap of the image and the crop area, which can be smaller than the size you set.
• With smart, the API uses content-aware cropping to keep the most important part of the image, such as a face.
• CropBy.ASPECTRATIO needs no size. Without one, the API returns the largest area of that ratio from the center of the image. Add a size with the resize method to scale the result.
• xval and yval have no effect with CropBy.DEFAULT and CropBy.ASPECTRATIO.
• Express width and height in pixels, for example 400, or as a percentage, for example 0.6 or '60p'.
• Each call replaces the whole crop value.
• For the full parameter rules, refer to the Crop Images section of the Image Delivery API reference.

Example

Basic usage: crop an image to 300 by 400 pixels

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().crop({ width: 300, height: 400 });

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?crop=300,400

All parameters: crop a region with safe and smart cropping

import { CropBy, ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().crop({
  width: 300,
  height: 400,
  xval: 50,
  yval: 80,
  cropBy: CropBy.REGION,
  safe: true,
  smart: true,
});

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?crop=300,400,x50,y80,safe,smart

Crop by offset, toward the top-right corner

import { CropBy, ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

// 80 places the crop near the right edge, and 20 places it near the top edge.
const transform = new ImageTransform().crop({ width: 200, height: 300, xval: 80, yval: 20, cropBy: CropBy.OFFSET });

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?crop=200,300,offset-x80,offset-y20

Crop to a 16:9 aspect ratio

import { CropBy, ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().crop({ width: 16, height: 9, cropBy: CropBy.ASPECTRATIO });

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?crop=16:9

dpr scales the requested image size for a screen with the given device pixel ratio.

Returns: ImageTransform. The same builder, for chaining.

Validation

• There is no client-side validation. dpr writes 0, a negative number, or any decimal as given. The Image Delivery API accepts a whole number from 1 to 10000, or a decimal from 0.0 to 9999.9999.
• Passing a string is a compile error, because dprValue is a number.
• Any rejection of the value comes from the Image Delivery API when the URL loads, not from dpr().

Behavior

• dpr writes dpr=<dprValue>.
• The API multiplies the width and height by the ratio, so a 300 pixel width with dpr(2) delivers a 600 pixel wide image. Set the width and height with the resize method.
• Without a width or height, dpr has no effect.
• For the sizing rules, refer to the Device Pixel Ratio section of the Image Delivery API reference.

Example

Basic usage: deliver a double-density image

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().resize({ width: 300, height: 500 }).dpr(2);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?width=300&height=500&dpr=2

fit sets the mode the Image Delivery API uses to fit the image within the width and height from resize.

Returns: ImageTransform. The same builder, for chaining.

Validation

• There is no client-side validation beyond the parameter type.
• fit accepts only a FitBy member. A plain string such as 'bounds' is a compile error, because FitBy is a string enum. Import FitBy from @contentstack/delivery-sdk.
• fit does not check that the builder has a width and height. Any rejection comes from the Image Delivery API when the URL loads, not from fit().

Behavior

• fit writes fit=<value>, where the value is the string behind the FitBy member. FitBy has the following two members:
  • FitBy.BOUNDS writes bounds. The API scales the image to fit inside the width and height and keeps its aspect ratio.
  • FitBy.CROP writes crop. The API scales and crops the image to fill the width and height exactly.
• Set both dimensions with the resize method. fit has no size of its own to apply.

Example

Basic usage: fit an image inside a 300 by 300 box

import { FitBy, ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().resize({ width: 300, height: 300 }).fit(FitBy.BOUNDS);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?width=300&height=300&fit=bounds

Fill a 300 by 300 box and crop the overflow

import { FitBy, ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().resize({ width: 300, height: 300 }).fit(FitBy.CROP);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?width=300&height=300&fit=crop

format converts the image to another file format.

Returns: ImageTransform. The same builder, for chaining.

Validation

• There is no client-side validation beyond the parameter type.
• format accepts only a Format member. A plain string such as 'png' is a compile error, because Format is a string enum. Import Format from @contentstack/delivery-sdk.

Behavior

• format writes format=<value>, where the value is the string behind the Format member. Format has the following seven members:
  • Format.GIF writes gif.
  • Format.PNG writes png.
  • Format.JPG writes jpg.
  • Format.PJPG writes pjpg, progressive JPEG.
  • Format.WEBP writes webp.
  • Format.WEBPLL writes webpll. The name stands for lossless WebP.
  • Format.WEBPLY writes webply. The name stands for lossy WebP.
• The API sends WebP only to a client whose Accept request header lists image/webp. Any other client receives the image in its original format. The auto method follows the same rule.
• Combine format with the quality method to set the compression level of a lossy format.
• For the formats the API supports, refer to the Convert Formats section of the Image Delivery API reference.

Example

Basic usage: convert an image to progressive JPEG

import { Format, ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().format(Format.PJPG);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?format=pjpg

Convert to lossy WebP at a set quality

import { Format, ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().format(Format.WEBPLY).quality(75);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?format=webply&quality=75

frame returns the first frame of an animated GIF as a still image.

Returns: ImageTransform. The same builder, for chaining.

Validation

• There is no client-side validation. frame takes no arguments and cannot fail.

Behavior

• frame writes frame=1. The SDK fixes the value at 1, the first frame.
• The parameter applies to animated GIF images. On an animated GIF, the API returns the first frame as a still image. frame does not check the image type, because the builder never reads the image.
• Combine frame with the format method to deliver the still frame in another format.
• For details, refer to the Frame section of the Image Delivery API reference.

Example

Basic usage: get the first frame of an animated GIF

import { ImageTransform } from '@contentstack/delivery-sdk';

const gifUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/banner.gif';

const transform = new ImageTransform().frame();

console.log(gifUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/banner.gif?frame=1

Deliver the first frame as a PNG

import { Format, ImageTransform } from '@contentstack/delivery-sdk';

const gifUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/banner.gif';

const transform = new ImageTransform().frame().format(Format.PNG);

console.log(gifUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/banner.gif?frame=1&format=png

orient rotates or flips the image.

Returns: ImageTransform. The same builder, for chaining.

Validation

• There is no client-side validation beyond the parameter type.
• Orientation is a numeric enum. TypeScript accepts a member such as Orientation.RIGHT or its number, such as 6, and rejects a number outside 1 to 8 at compile time.
• Any rejection comes from the Image Delivery API when the URL loads, not from orient().

Behavior

• orient writes orient=<number>, where the number is the value behind the Orientation member. Orientation has the following eight members:
  • Orientation.DEFAULT writes 1, the original orientation.
  • Orientation.FLIP_HORIZONTAL writes 2.
  • Orientation.FLIP_HORIZONTAL_VERTICAL writes 3.
  • Orientation.FLIP_VERTICAL writes 4.
  • Orientation.FLIP_HORIZONTAL_LEFT writes 5.
  • Orientation.RIGHT writes 6.
  • Orientation.FLIP_HORIZONTAL_RIGHT writes 7.
  • Orientation.LEFT writes 8.

Example

Basic usage: rotate an image to the right

import { ImageTransform, Orientation } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().orient(Orientation.RIGHT);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?orient=6

Flip an image horizontally

import { ImageTransform, Orientation } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().orient(Orientation.FLIP_HORIZONTAL);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?orient=2

overlay places another image on top of the base image, by the overlay image's relative URL.

Returns: ImageTransform. The same builder, for chaining.

Validation

• There is no client-side validation. overlay writes an empty or malformed relativeURL as given.
• Known issue: In 5.x, overlay does not URL-encode relativeURL, so a &, ?, or # in the path breaks the query string. Pass a plain path such as /v3/assets/....
• overlay skips a falsy optional property. A width or height of 0 writes nothing.
• Known issue: In 5.x, overlay accepts pad but writes no overlay padding to the URL, and reports no error. To pad the overlay, append the overlay-pad parameter to the URL yourself, as the Overlay Pad section of the Image Delivery API reference describes. The padding method pads the base image, not the overlay.
• Any rejection of a value comes from the Image Delivery API when the URL loads, not from overlay().

Behavior

• overlay writes overlay=<relativeURL>, and adds overlay-align, overlay-repeat, overlay-width, and overlay-height for the properties you pass.
• align takes an OverlayAlign member or an array of them. The SDK joins an array with commas, for example bottom,right. OverlayAlign has the following six members:
  • OverlayAlign.TOP writes top.
  • OverlayAlign.BOTTOM writes bottom.
  • OverlayAlign.LEFT writes left.
  • OverlayAlign.RIGHT writes right.
  • OverlayAlign.MIDDLE writes middle.
  • OverlayAlign.CENTER writes center.
• Without align, the API places the overlay in the middle of the base image. A single value moves it to that edge and keeps it centered along the edge. Two values combine a vertical and a horizontal position in either order, so bottom,right places the overlay in the bottom-right corner.
• repeat takes an OverlayRepeat member. OverlayRepeat has the following three members:
  • OverlayRepeat.X writes x, repeating the overlay horizontally.
  • OverlayRepeat.Y writes y, repeating the overlay vertically.
  • OverlayRepeat.BOTH writes both, repeating the overlay in both directions.
• Express width and height in pixels as a whole number from 1 to 8192. You can also pass a percentage of the output image, for example 0.5 or '50p'.
• For the full parameter rules, refer to the Overlay Settings section of the Image Delivery API reference.
• A second overlay call replaces overlay and every optional key you pass again. Keys you leave out keep their earlier values.

Example

Basic usage: place a logo over an image

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';
const logoPath = '/v3/assets/blteae40eb499811073/blt3d8b2c5a7e1f4b09/59e0c41ac0eddd140d5a8e3f/logo.png';

const transform = new ImageTransform().overlay({ relativeURL: logoPath });

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?overlay=/v3/assets/blteae40eb499811073/blt3d8b2c5a7e1f4b09/59e0c41ac0eddd140d5a8e3f/logo.png

All parameters: align, repeat, and size the overlay

import { ImageTransform, OverlayAlign, OverlayRepeat } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';
const logoPath = '/v3/assets/blteae40eb499811073/blt3d8b2c5a7e1f4b09/59e0c41ac0eddd140d5a8e3f/logo.png';

const transform = new ImageTransform().overlay({
  relativeURL: logoPath,
  align: [OverlayAlign.BOTTOM, OverlayAlign.RIGHT],
  repeat: OverlayRepeat.X,
  width: '50p',
  height: 100,
  pad: 10, // Discarded: no overlay padding reaches the URL
});

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?overlay=/v3/assets/blteae40eb499811073/blt3d8b2c5a7e1f4b09/59e0c41ac0eddd140d5a8e3f/logo.png&overlay-align=bottom,right&overlay-repeat=x&overlay-width=50p&overlay-height=100

padding adds pixels around the edges of the image, for example to create white space or a border.

Returns: ImageTransform. The same builder, for chaining.

Validation

• There is no client-side validation. padding writes negative values and arrays of any length as given.
• An empty array writes pad= with no value.
• Passing a string is a compile error, because padding is a number or a number[].
• Any rejection of the values comes from the Image Delivery API when the URL loads, not from padding().

Behavior

• padding writes pad=<padding>. The SDK joins an array with commas.
• Pass one number to pad every edge by the same amount.
• Pass two numbers to pad the top and bottom by the first and the right and left by the second.
• Pass three numbers to pad the top by the first, the right and left by the second, and the bottom by the third.
• Pass four numbers to pad each edge separately, in the order top, right, bottom, left.
• Use the bgColor method to set the color of the added area. Without it, the padding is white, or transparent when the output format supports transparency.
• When the URL also sets a canvas, the API ignores the padding.
• padding pads the base image. It does not pad an image you add with the overlay method.

Example

Basic usage: add 20 pixels of padding to every edge

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().padding(20);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?pad=20

Pad each edge separately with a gray background

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

// Top, right, bottom, left
const transform = new ImageTransform().padding([25, 50, 75, 90]).bgColor('cccccc');

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?pad=25,50,75,90&bg-color=cccccc

quality sets the compression level the Image Delivery API applies to a lossy image format.

Returns: ImageTransform. The same builder, for chaining.

Validation

• There is no client-side validation. quality writes 0, a negative number, a decimal, or a value above 100 as given.
• Passing a string, or calling quality() with no argument, is a compile error, because qualityNum is a required number.
• Any rejection of the value comes from the Image Delivery API when the URL loads, not from quality(). A value above 100 fails with status 502. The API ignores 0 and negative values and returns the image unchanged.

Behavior

• quality writes quality=<qualityNum>.
• A lower number means higher compression and a smaller file. The setting is meant for lossy formats such as JPEG and WebP. A PNG image can also come back smaller, with fewer colors.
• When the compressed file would be larger than the original, the API returns the original file.
• Combine quality with the format method to convert the image to a lossy format first.

Example

Basic usage: compress an image to quality 50

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().quality(50);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?quality=50

resize sets the width and height the Image Delivery API scales the image to.

Returns: ImageTransform. The same builder, for chaining.

Validation

• There is no client-side validation. resize writes negative or out-of-range sizes as given.
• resize skips a falsy property. A width or height of 0 or '' writes nothing.
• disable accepts any string, and any non-empty value writes disable=upscale. The SDK ignores the text you pass.
• Calling resize() with no argument is a compile error. Pass an object, even an empty one. resize({}) writes nothing.
• Any rejection of a size comes from the Image Delivery API when the URL loads, not from resize().

Behavior

• resize writes width=<width>, height=<height>, and disable=upscale for the properties you pass, and leaves the others out of the URL.
• Express a size in pixels, for example 400, or as a percentage, for example 0.6 or '60p'.
• With only one of width and height, the API keeps the image's aspect ratio.
• With disable: 'upscale', the API does not enlarge an image that is smaller than the requested size.
• A second resize call writes only the properties it receives, so resize({ width: 300 }).resize({ height: 200 }) sets both.
• Use the fit, dpr, and resizeFilter methods to set the fit mode, pixel density, and resampling filter for the new size.

Example

Basic usage: resize an image to 300 pixels wide

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().resize({ width: 300 });

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?width=300

All parameters: resize to a fixed box without upscaling

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().resize({ width: 300, height: 200, disable: 'upscale' });

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?width=300&height=200&disable=upscale

Resize by percentage

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

// Half of the original width
const transform = new ImageTransform().resize({ width: '50p' });

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?width=50p

resizeFilter sets the resampling filter the Image Delivery API uses when it resizes the image.

Returns: ImageTransform. The same builder, for chaining.

Validation

• There is no client-side validation beyond the parameter type.
• resizeFilter accepts only a ResizeFilter member. A plain string such as 'bicubic' is a compile error, because ResizeFilter is a string enum. Import ResizeFilter from @contentstack/delivery-sdk.
• Any rejection comes from the Image Delivery API when the URL loads, not from resizeFilter().

Behavior

• resizeFilter writes resize-filter=<value>, where the value is the string behind the ResizeFilter member. ResizeFilter has the following five members:
  • ResizeFilter.NEAREST writes nearest.
  • ResizeFilter.BILINEAR writes bilinear.
  • ResizeFilter.BICUBIC writes bicubic.
  • ResizeFilter.LANCZOS2 writes lanczos2.
  • ResizeFilter.LANCZOS3 writes lanczos3.
• The filter can apply only when the URL also resizes the image. Set the size with the resize method. Without a size, the API returns the original image.
• For a description of each filter, refer to the Resize-filter section of the Image Delivery API reference.

Example

Basic usage: resize with the Lanczos 3 filter

import { ImageTransform, ResizeFilter } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().resize({ width: 500, height: 550 }).resizeFilter(ResizeFilter.LANCZOS3);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?width=500&height=550&resize-filter=lanczos3

saturation adjusts the intensity of the colors in the image.

Returns: ImageTransform. The same builder, for chaining.

Validation

• There is no client-side validation. saturation writes a value outside -100 to 100 as given.
• Passing a string is a compile error, because saturationValue is a number.
• Any rejection of the value comes from the Image Delivery API when the URL loads, not from saturation(). The API rejects a value outside -100 to 100 with status 400.

Behavior

• saturation writes saturation=<saturationValue>, keeping any decimal places, for example saturation=-45.5.
• A positive value increases the saturation, a negative value decreases it, and 0 leaves it unchanged.

Example

Basic usage: increase the color intensity of an image

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().saturation(40);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?saturation=40

Reduce the color intensity by a decimal amount

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().saturation(-45.5);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?saturation=-45.5

sharpen increases the definition of the edges of objects in the image.

Returns: ImageTransform. The same builder, for chaining.

Validation

• There is no client-side validation. sharpen writes values outside the documented ranges as given.
• Omitting any of the three arguments is a compile error, because the signature gives none of them a default.
• IMPORTANT: The three parameters are positional numbers, so swapped arguments compile without error. sharpen(1000, 5, 2) writes a1000,r5,t2, a different setting from sharpen(5, 1000, 2). Pass them in the order amount, radius, threshold.
• Any rejection of a value comes from the Image Delivery API when the URL loads, not from sharpen(). The API rejects an amount above 10, a radius above 1000, or a threshold above 255 with status 400.

Behavior

• sharpen writes sharpen=a<amount>,r<radius>,t<threshold>.
• A higher threshold leaves more low-contrast edges unsharpened.
• To soften the image instead, use the blur method.

Example

Basic usage: sharpen an image

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

// amount 5, radius 1000, threshold 2
const transform = new ImageTransform().sharpen(5, 1000, 2);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?sharpen=a5,r1000,t2

trim removes pixels from the edges of the image, for example a border or white space.

Returns: ImageTransform. The same builder, for chaining.

Validation

• There is no client-side validation. trim writes negative values and arrays of any length as given.
• An empty array writes trim= with no value.
• Passing a string is a compile error, because trimValues is a number or a number[].
• Any rejection of the values comes from the Image Delivery API when the URL loads, not from trim().

Behavior

• trim writes trim=<trimValues>. The SDK joins an array with commas.
• Pass one number to trim every edge by the same amount.
• Pass two numbers to trim the top and bottom by the first and the right and left by the second.
• Pass three numbers to trim the top by the first, the right and left by the second, and the bottom by the third.
• Pass four numbers to trim each edge separately, in the order top, right, bottom, left.
• A value below 1 trims a fraction of the image size, for example 0.1 for 10 percent.
• A trim that removes the whole image fails with status 400 when the URL loads.

Example

Basic usage: trim 20 pixels from every edge

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

const transform = new ImageTransform().trim(20);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?trim=20

Trim each edge by a different amount

import { ImageTransform } from '@contentstack/delivery-sdk';

const imageUrl = 'https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg';

// Top, right, bottom, left
const transform = new ImageTransform().trim([25, 50, 75, 90]);

console.log(imageUrl.transform(transform));
// https://images.contentstack.io/v3/assets/blteae40eb499811073/bltc5064f36b5855343/59e0c41ac0eddd140d5a8e3e/owl.jpg?trim=25,50,75,90