The image pipeline enables you to dynamically crop and resize images for your website, among other changes. It also includes automatic JPG/PNG to WebP conversion.

Automatic WebP conversion

Newer browsers support WebP as an image format. In a lot of cases WebP can be a smaller image file size. The CDN will automatically convert a JPG or PNG image to a WebP image on the fly if the visitor's browser supports it. There is nothing that you need to do to enable this.

However, if the browser is older and doesn't support WebP and you uploaded a WebP image to your website, then the CDN will automatically convert that WebP image to a PNG file.

The WebP conversion does not change your original image. It happens in the CDN when the image is requested. If your image is a JPG image then the HTML will still show a ".jpg" file extension. However, the response from the CDN will include WebP data and headers.

Image modifications

You can do the following image modifications to an image. They all happen in the CDN and don't alter your original image.

In order to use any of the modifications you must use the Twig image object to apply the change and output your image.

For example, here is how you can crop an image and output it.

{% do image.crop(400, 200) %}
{{ image.tag }}

In all of the examples on this page the "image" value represents the image variable that you're working with. Most likely your code will be different.

For example, if you're referencing an image uploaded in the theme editor then you might use this:

{% do _core.theme.settings.myImage.crop('400x200') %}

Replace the "image" value in the examples on this page with the actual variable name for your image.

Chaining methods

Like most HTML object methods, you can chain the image modifications together. For example, to crop, rotate and output at once, you could do this.

{{ do image.crop(1000, 400).rotate().tag() }}

Or, you could apply multiple modifications and then output later.

{% do image.crop(1000, 400).rotate().alt('My alt text') %}
{{ image.tag() }}

Playground

You can test some image modifications at https://aptuitiv.github.io/image-transformation-tests. This shows the resulting image to apply the modifications. 

(You can technically manually build your image URL to include the modification parameters. However, we recommend that you use the modification methods below as they are easier.)

Modify options

There are specific methods to set up modifications below, but you can also use the modify() method to apply one or more modifications. The modify() method takes the following methods.

Any of the modification methods below that take an option object as a parameter supports these options. This means that while you're calling the crop() method, you can pass a set of options that applies the cropping, but it can also apply other modifications.

Aspect ratios

Aspect ratios can be used to crop and resize an image. They follow this format: WIDTHxHEIGHT.

Examples:

  • 16x9
  • 2000x700
  • 3x4

Crop positions

When cropping an image the default is to crop the image from the center of the image.  You can adjust that with the crop position. The following values are supported.

  • bottom
  • bottomleft (bottom left)
  • bottomright (bottom right)
  • center
  • left (left center)
  • right (right center)
  • top
  • topleft (top left)
  • topright (top right)

Modify

You can use the modify() method to apply an image modification, although we recommend one of the purpose-built methods below as they are easier.

The modify method as the following signature.

modify(options)

For example, you can blur, crop, resize, and rotate at once.

{% do image.modify({blur: true, c: 'topleft', w: 400, h: 100, rotate: 45}) %}

Blur

The blur value must be between 0.3 and 1000. If no value is passed then 10 is used.

The blur method has the following signature.

blur(number)

{% do image.blur(30) %}

Crop

You can crop an image based on a specific height and width, an aspect ratio, or a combination of an aspect ratio and a width. You can also specify the crop position.

When the image is cropped the height and width values for the image tag are also updated to reflect the new size.

The crop method has the following signature.

crop(width, height)
crop(width, height, position)
crop(aspectRatio)
crop(aspectRatio, position)
crop(options)

By default the the crop position will be the center of the image. You can have it crop starting at the bottom, bottom right, bottom left, left, right, top, top right, or top left of the image.

The options an be any of the modification options.

Examples

Crop to a specific width and height.

{% do image.crop(1000, 400) %}

Crop to a specific height and width with a crop position.

{% do image.crop(1000, 400, 'top') %}

Crop to an aspect ratio. The resulting image will be the same width as the original.

{% do image.crop('16x9') %}

Crop to an aspect ratio with a crop position. The resulting image will be the same width as the original.

{% do image.crop('16x9', 'bottom') %}

Crop with a set of modify options. The common options used include:

Use this if you want to specify an aspect ratio crop with a specific width.

{% do image.crop({ar: '400x100', width: 300, crop: 'top'}) %}

Flip horizontal

To flip the image horizontally you use the flipX() method. It does not take any paramters.

{% do image.flipX() %}

Flip vertical

To flip the image vertically you use the flipY() method. It does not take any paramters.

{% do image.flipY() %}

Format

You can specify a specific image format for the image output. The following format values are supported.

  • avif
  • jpg
  • original
  • png
  • webp

The format method has the following signature.

format(format)

Output an image in the AVIF format.

{% do image.format('avif') %}

Grayscale

You can change an image to output in grayscale format.

To support the US and UK version of gray the following methods are equivalent.

gray()
grayscale()
grey()
greyscale()

The methods do not have any parameters.

{% do image.gray() %}

Negative

You can output the negative version of the image with the negative() method. It has no parameters.

{% do image.negative() %}

Quality

Change the quality of the image with the quality() method. It has the following signature.

quality(value)

The value can be between 1 and 100. If another value is passed then the quality is not changed.

{% do image.quality(65) %}

Resize

You can resize an image, or you can resize and crop an image.

When the image is resized the height and width values for the image tag are also updated to reflect the new size.

The resize method has the following signature.

resize(width)
resize(width, height)
resize(aspectRatio)
resize(options)

When an image is resized the original aspect ratio of the image is maintained. The only time this doesn't happen is if the image is also cropped.

If the image is smaller than the resize size then no change takes place. Images are only resized down. They are not scaled up.

The options can be any of the modification options.

In a majority of cases, if you're specifying a height and width, or an aspect ratio to resize to, you also want to crop the image to make sure that you get the dimensions you expect.

{% do image.resize({width: 600, height: 300, crop: true}) %}

Examples

Resize an image to a specific width. The image will maintain it's original aspect ratio.

{% do image.resize(400) %}

Resize an image to a specific height and width. The image will be resized to fit within these dimensions while maintaining it's original aspect ratio.

{% do image.resize(600, 300) %}

Resize an image to a specific height and width and crop it to ensure that it's the exact dimensions.

{% do image.resize({width: 600, height: 300, crop: true}) %}

Resize an image to fit within an aspect ratio. The image will be resized to fit within these dimensions while maintaining it's original aspect ratio.

{% do image.resize('16x9') %}

Resize an image to an aspect ratio and crop to ensure that it's the correct dimensions. In this example we specify the "top" crop position.

{% do image.resize({ar: '16x9', crop: 'top'}) %}

Rotate

Rotate an image by a specific degree amount. You can also specific a background color for the image if the rotated image isn't perfectly vertical or horizontal.

The rotate method the following signature.

rotate(degrees)
rotate(degrees, color)

The degrees value can be any valid positive or negative number.

The color value can be a valid HEX color or a named color (blue, red, etc). RGB, RGBA, and HSLA are not supported. You can, however, use a eight-character version of a HEX to enable a semi-transparent background if you want.

Rotate an image 45 degrees.

{% do image.rotate(45) %}

Rotate an image -35 degrees with a background.

{% do image.rotate(-35, '#ff0000') %}

Rotate an image 6904 degrees. (This is a crazy example, but it shows that you can use values greater than 360.)

{% do image.rotate(6904) %}