# Templating

# Transforms and placeholders

# craft.imagerx.transformImage(image, transform [, transformDefaults=null, configOverrides=null])

The main transform method. Returns either a transformed image model if just one transform object were passed, or an array of transformed image models if an array were passed. Takes the following parameters:

image: Image to be transformed. This can be either an Asset element, a previously transformed Imager transformed image model, the path to an image relative to the webroot, or the url to an external image.
transform: An object, or an array of objects, containing the transform parameters to be used. See the Usage- and Transform parameters-sections for more information.
transformDefaults: An object containing any default transform parameters that should be applied to all transforms.
configOverrides: An object containing any overrides to the default config settings that should be used for this transform. See the Configuration-section for information on which settings that can be overridden.

# craft.imagerx.srcset(images [, descriptor='w'])

Outputs a srcset string from an array of transformed images.

images: An array of transformed images, or anything else that supports the TransformedImageInterface (opens new window) interface.
descriptior: A string indicating which size descriptor should be used in the srcset. 'w', 'h' and 'w+h' is supported at the moment. Please note that 'w+h' isn't standards-compliant, but is useful for instance when using lazysizes (opens new window) and their bgset plugin.

# craft.imagerx.placeholder([config = null])

Outputs an image placeholder. The config object takes the following parameters:

type: Type of placeholder. Defaults to 'svg'. Available types are 'svg', 'gif', 'silhouette' and 'blurhash' (new in 4.1.12).
width: Width of the placeholder. Defaults to '1'.
height: Height of the placeholder. Defaults to '1'.
color: Color of the placeholder. Defaults to 'transparent'.
source: Source image that should be used to create silhouette style svgs. Only relevant for silhouette placeholders.
fgColor: Foreground color for silhouette style svgs. Color is used as background. Only relevant for silhouette placeholders.
size: Size multiplicator for silhouette style svgs. Only relevant for silhouette placeholders.
silhouetteType: Type of silhouette, available values are '' and 'curve'. Only relevant for silhouette placeholders.
hash: Blurhash string. Only relevant for blurhash placeholders.
format: Image format of encoded image. Defaults to 'png'. Available formats are 'png', 'gif' and 'jpg'. Only relevant for blurhash placeholders.

# craft.imagerx.base64Pixel([width=1, height=1, color='transparent'])

This method has been deprecated, please use craft.imagerx.placeholder instead.
Outputs a base64 encoded SVG image.

width: Width of the placeholder. Defaults to '1'.
height: Height of the placeholder. Defaults to '1'.
color: Color of the placeholder. Defaults to 'transparent'.

# Helper functions

# craft.imagerx.serverSupportsWebp()

Returns true or false depending on if the server has support for WEBP; either through the active image driver (opens new window), or configured as a custom encoder.

# craft.imagerx.serverSupportsAvif()

Returns true or false depending on if the server has support for AVIF; either through the active image driver (opens new window), or configured as a custom encoder.

# craft.imagerx.serverSupportsJxl()

Returns true or false depending on if the server has support for JPEG XL; either through the active image driver (opens new window), or configured as a custom encoder..

# craft.imagerx.clientSupports(format)

Returns true or false depending on if the client has support for the format. This is deducted from the Accept header that the client sends.

WARNING

Safari does not send the appropriate accept headers, and can not be relied upon. You should probably not use this method of detecting client support for image formats.

Example:

Support for WEBP: {{ craft.imagerx.clientSupports('webp') ? 'yes' : 'no' }}<br>
Support for AVIF: {{ craft.imagerx.clientSupports('avif') ? 'yes' : 'no' }}<br>

If you use template caching, or any kind of front side/static cache (Blitz, Cloudflare, Varnish, Fastly, etc), make sure you create different caches based on if the client has support for the format or not. For template caching, adding a string to the key based on this variable, is one way to solve it. Example:

{% cache using key "my-content" ~ (craft.imagerx.clientSupports('webp') ? "-with-webp") %}  
...
{% endcache %}

# craft.imagerx.isAnimated(image)

Returns true or false depending on if the supplied image is animated or not (only gif support at the moment).

# craft.imagerx.imgixEnabled()

Returns true or false depending on if Imgix is enabled.

# craft.imagerx.transformer()

Returns the handle for the configured transformer.

# craft.imagerx.hasNamedTransform(name)

Returns true or false depending on if a named transform with handle name exists or not.

# craft.imagerx.getNamedTransform(name)

Returns a named transform with handle name if it exists. Returns null if it doesn't exist.

# Color analysis and manipulation

# craft.imagerx.getDominantColor(image [, quality=10, colorValue='hex', area=null])

Gets the dominant color of an image. Uses Color Thief (opens new window) for all the magic.

image: Image to get dominant color from. Can be any of the types that transformImage can handle.
quality: Calculation accuracy of the dominant color. 1 is the highest quality, 10 is the default. Be aware that there is a trade-off between quality and speed/memory consumption!
colorValue: Indicates which data format the returned color is in. Allowed values are 'hex' (default) and 'rgb'. If rgb is selected, the value is an array with red as index 0, green as index 1 and blue as index 2.
area: An area of the image that should be used for analysis. Should be an object with x, y, width and height. For instance: { x: 0, y: 0, height: 200, width: 1000 }.

# craft.imagerx.getColorPalette(image [, colorCount=8, quality=10, colorValue='hex', area=null])

Gets the color palette of an image. Uses Color Thief (opens new window) for all the magic.

image: Image to get palette from. Can be any of the types that transformImage can handle.
colorCount: Number of colors to include in palette.
quality: Calculation accuracy of the dominant color. 1 is the highest quality, 10 is the default. Be aware that there is a trade-off between quality and speed/memory consumption!
colorValue: Indicates which data format the returned color is in. Allowed values are 'hex' (default) and 'rgb'. If rgb is selected, the value is an array with red as index 0, green as index 1 and blue as index 2.
area: An area of the image that should be used for analysis. Should be an object with x, y, width and height. For instance: { x: 0, y: 0, height: 200, width: 1000 }.

# craft.imagerx.hex2rgb(color)

Converts a hexadecimal color value to rgb. Input value must be a string. Output value is an array with red as index 0, green as index 1 and blue as index 2.

# craft.imagerx.rgb2hex(color)

Converts a rgb color value to hexadecimal. Input value must be an array with red as index 0, green as index 1 and blue as index 2. Output value is a string.

# craft.imagerx.getBrightness(color)

Calculates color brightness (opens new window) on a scale from 0 (black) to 255 (white).

# craft.imagerx.getPercievedBrightness(color)

Calculates the perceived brightness (opens new window) of a color on a scale from 0 (black) to 255 (white).

# craft.imagerx.getRelativeLuminance(color)

Calculates the relative luminance (opens new window) of a color on a scale from 0 (black) to 1 (white).

# craft.imagerx.getBrightnessDifference(color1, color2)

Calculates brightness difference (opens new window) on a scale from 0 to 255.

# craft.imagerx.getColorDifference(color1, color2)

Calculates color difference (opens new window) on a scale from 0 to 765.

# craft.imagerx.getContrastRatio(color1, color2)

Calculates the contrast ratio (opens new window) between two colors on a scale from 1 to 21.

# craft.imagerx.getHue(color)

Get the hue channel of a color.

# craft.imagerx.getLightness(color)

Get the lightness channel of a color.

# craft.imagerx.getSaturation(color)

Get the saturation channel of a color.

# craft.imagerx.isBright(color [, threshold=127.5])

Checks brightness(color) >= threshold. Accepts an optional threshold float as the last parameter with a default of 127.5.

# craft.imagerx.isLight(color [, threshold=50])

Checks lightness(color) >= threshold. Accepts an optional threshold float as the last parameter with a default of 50.0.

# craft.imagerx.looksBright(color [, threshold=127.5])

Checks perceived_brightness(color) >= threshold. Accepts an optional threshold float as the last parameter with a default of 127.5.

# Twig filters

# srcset([descriptor='w'])

Outputs a srcset string from an array of transformed images.

{% set transformedImages = craft.imagerx.transformImage(image, [{ width: 400 },{ width: 1200 }], { ratio: 16/9 }, { fillTransforms: true }) %}

<img src="{{ craft.imagerx.placeholder({ width: 16, height: 9 }) }}" sizes="100vw" srcset="{{ transformedImages | srcset }}">

← Configuration Transform parameters →