Learn

transform

Manipulate your images to your heart's desire (new in 1.5.3)

{{ transform }}

The Transform tag is used for resizing, cropping, and manipulating your images on the fly, right from your templates.

It is used as a single tag and returns the URL to your final image, so you’ll want to use it inside an img tag. It’s also smart enough to know if the image has been created before and won’t reprocess the transformations.

Sample Usage

<img src="{{ transform src="/img/hat.jpg" width="600" flip="h" }}" />

Save Location

By default, Transform will save your transformed images to the same location as the input image. The filename will include markers for the parameters used so transforms won’t be run more than once.

You can use a global setting to change this behavior, which can then be overridden on a per-tag level with the destination parameter.

_transform_destination: /assets/


Parameters

src

The path to the image you wish to process. This can be a variable.

Example: src="/assets/img/mountain.jpg"

destination

Overwrite the default location (and _transform_destination system setting) to save this tag’s files somewhere specific. Be careful of prefix and trailing slashes (hint: you probably want them) as they may result in undesired file locations.

Example: destination="/assets/{{segment_1}}/"

quality

Define optionally the quality of the image. It is normalized for all file types to a range from 0 (poor quality, small file) to 100 (best quality, big file).

Default: 75

width

The desired width of the image in pixels, if cropping or resizing.

Example: width="800"

height

The desired height of the image in pixels, if cropping or resizing.

Example: height="600"

action

Available options:

  • resize Will resize to the shortest given side based on given height and width
  • crop Will crop the image based on your given width and height
  • smart Combines resize and crop to find the best fitting aspect ratio of your given width and height

Default: resize

ratio

If ratio is set to yes the aspect ratio of the image will be preserved during the resize process.

Default: yes

upsize

Determines whether the image can be upsized.

Default: yes

pos_x

X-Coordinate of the top-left corner when cropping.

Default: 0

pos_y

Y-Coordinate of the top-left corner when cropping.

Default: 0

rotate

Rotate the current image by a given angle, specified in degrees.

Example: `rotate=”-90”

flip

Mirror the current image horizontally or vertically.

Available options:

  • h for horizontal
  • v for vertical

Example: flip="h"

blur

Apply a Gaussian blur filter with a specified amount of strength. Usually values between 1 and 15 will suffice.

Example: blur="5"

pixelate

Applies a pixelation effect to the current image with a given size of pixels. Note: turns on the advanced mode of the GD Library.

Example: pixelate="10"

greyscale

Turns your image into a greyscale version of its former self.

Example: greyscale="yes"

type

The type of image you want saved.

Available options:

  • jpg
  • png
  • gif

Default: Whatever type the original image was.

watermark

You can add watermarks to your images with the following options (chanined by pipes `|“):

  • source image
  • position (e.g. top-left, bottom-right)
  • X offset
  • Y offset
watermark="/assets/img/logo.png|bottom-left|10|10"

You can even have multiple watermarks if that’s your thing:

watermark="/assets/img/logo.png|bottom-left,/assets/img/another_logo.png|top-right"

Use Cases

For these examples, we’ll assume your image is in a variable called {{ photo }}. That makes everything easier!

Case 1

You want to resize an image to fit a specific width but don’t care about height. Easy.

<img src="{{ transform src="{{ photo }}" width="600" }}" />

Case 2

You want a specific width and height but don’t want to mess with the aspect ratio (good call). It’s time for “smart” mode. This will resize the image to the shortest edge and then smart crop to finish the job.

<img src="{{ transform src="{{ photo }}"width="600" height="300" action="smart }}" />

Case 3

Let’s say you want to leave your original image intact, create a thumbnail, and open the original in a lightbox. We’ll leave the lightbox implementation specifics to your imagination, but in general it would look something like this:

<a href="{{ photo }}" class="lightbox">
  <img src="{{ transform src="{{ photo }}" width="150"height="150"action="smart" }}"  />
</a>

Got a complicated use case you want to see documented? Ask away!

This article was last updated on September 13th, 2016. Find an error? Please let us know!