img_url

Creates a thumbnail for an image attachment and returns it’s url. You can pass a width parameter and extra arguments with the img_url filter to define what thumbnail you want. The first parameter is the width.

Input:

Output:

If you only pass the one argument (width) the aspect ratio is maintained. You can add the height argument to force dimensions, but also arguments like blur and dpr to create a thumbnail of the image to your liking.

Input:

Output:

Note: img_url only works on an attachment or the attachment src (attachment.src). Also GIF files do not work.

Image Cropper:

• For attachment input: img_url displays the cropped version in the admin editor. Note that the crop option will override existing cropped version.

• For attachment src input, img_url will not automatically display the cropped version. It's recommended to include crop: attachment.crop along with the src input.

Below you can find all arguments you can use on the img_url and what they do.

width

Specifies the width of the output image in pixels.

If the width is set to 0 its value will be automatically calculated based on the supplied height value, so that the original image aspect ratio is preserved. If both width and height are supplied, the image will be resized according to the mode setting.

height

Specifies the height of the output image in pixels.

If the height is omitted or set to 0 (default) its value will be automatically calculated based on the supplied width value, so that the original image aspect ratio is preserved. If both width and height are supplied, the image will be resized according to the mode setting.

mode

Controls the resize mode when both a width and height are specified.

Available modes:

• fit: Resize to fit within the boundaries defined by the width and height parameters, while maintaining the original aspect ratio. If the output aspect ratio differs from the original, only one of the dimensions (width or height) will equal its set value, while the other will be smaller.

• crop: Resize to fill the entire area defined by width and height, by maintaining the aspect ratio, but possibly clipping part of the image.

• stretch: Resize to fill the entire area defined by width and height, by modifying the aspect ratio.

The default mode is fit.

Open

 

mode: "fit"

Open

 

mode: "crop"

crop

Allows you to specify which part of the image is used.

To crop an image, you specify four parameters – the origin x and y (which defines the top left of the crop rectangle) and the dimensions w and h (which define the size of the rectangle).

Cropping is applied before other transformations. This means that the crop values must be relative to the original size of the image, even if you resize it in the same img_url filter. Note also that resizing may cause additional cropping of some part of the image if mode: "crop" is used.

Note: you can generate crop values by using inline crop on attachments.

dpr

Specifies the device pixel ratio, between 0.1 and 10.0.

Acts as a multiplier for both the width and height. For example, using width: 320, height: 150, dpr: 2 is equivalent to width: 640, height: 300.

This allows you to easily specify an image with the correct resolution for high dpi devices such as iPhones.

The default dpr is 1.0.

blur

Blurs the image by a value relative to the image size, between 0 and 100. The default blur value is 0(no blur).

brightness, contrast, hue, saturation and gamma

For each image setting of brightness, contrast, hue, saturation and gamma, it adjusts the setting of the image, with values between -100 and 100.

The default value is 0 (no adjustment).

A saturation value of -100 turns the image into grayscale.

quality

Sets the quality of the output image, with values between 0 and 100. This setting only affects JPEG images. Higher quality values result in images with a larger file size.

The default quality is 85, which is also recommended, since it’s a perfect balance between file size and image quality.

format

Normally images are processed and presented in the same format as the input image. This parameter allows you to force the output image to a particular format.

You can force images to be output as jpeg, png or webp, using format: "jpeg", format: "png" or format: "webp".

If the original image has an alpha channel (e.g. transparent PNGs), a white background will be applied if the output format does not support transparency. 

upscale

Can be 'true' or 'false' Configures whether images smaller than the provided width/height arguments are upscaled or not. Default: 'true'