# Templating
# Transforms and placeholders
# craft.imager.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 string to a previously transformed Imager image, or a string 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 settings that should be applied to each transform. If transform properties given here are specified in an individual transform, the property value of the individual transform will be used.
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.imager.srcset(images [, descriptor='w'])
Outputs a srcset string from an array of transformed images.
images: An array of Imager_ImageModel objects, or anything else that support the 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 'h' isn't standards-compliant, but is useful for instance when using Lazysizes and their bgset plugin.
# craft.imager.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' and 'silhouette'.
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.
# craft.imager.base64Pixel([width=1, height=1, color='transparent'])
This method has been deprecated, please use craft.imager.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.imager.serverSupportsWebp()
Returns true or false depending on if the server has support for WEBP or not. This could either indicate built in support for webp in the current image driver, GD or Imagick, or the presence of the cwebp binary if this has been enabled.
# craft.imager.serverSupportsAvif()
Returns true or false depending on if Imager has been configured to support AVIF.
# craft.imager.serverSupportsJxl()
Returns true or false depending on if Imager has been configured to support JPEG XL.
# craft.imager.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.imager.clientSupports('webp') ? 'yes' : 'no' }}<br>
Support for AVIF: {{ craft.imager.clientSupports('avif') ? 'yes' : 'no' }}<br>
If you use template caching, or any kind of front side cache (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.imager.clientSupports('webp') ? "-with-webp") %}
...
{% endcache %}
# craft.imager.isAnimated(image)
Returns true or false depending on if the supplied image is animated or not (only gif support at the moment).
# craft.imager.imgixEnabled()
Returns true or false depending on if Imgix is enabled.
# craft.imager.transformer()
Returns the handle for the configured transformer.
# craft.imager.hasNamedTransform(name)
Returns true or false depending on if a named transform with handle name exists or not.
# craft.imager.getNamedTransform(name)
Returns a named transform with handle name if it exists. Returns null if it doesn't exist.
# Color analysis and manipulation
# craft.imager.getDominantColor(image [, quality=10, colorValue='hex'])
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.
# craft.imager.getColorPalette(image [, colorCount=8, quality=10, colorValue='hex'])
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.
# craft.imager.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.imager.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.imager.getBrightness(color)
Calculates color brightness (opens new window) on a scale from 0 (black) to 255 (white).
# craft.imager.getPercievedBrightness(color)
Calculates the perceived brightness (opens new window) of a color on a scale from 0 (black) to 255 (white).
# craft.imager.getRelativeLuminance(color)
Calculates the relative luminance (opens new window) of a color on a scale from 0 (black) to 1 (white).
# craft.imager.getBrightnessDifference(color1, color2)
Calculates brightness difference (opens new window) on a scale from 0 to 255.
# craft.imager.getColorDifference(color1, color2)
Calculates color difference (opens new window) on a scale from 0 to 765.
# craft.imager.getContrastRatio(color1, color2)
Calculates the contrast ratio (opens new window) between two colors on a scale from 1 to 21.
# craft.imager.getHue(color)
Get the hue channel of a color.
# craft.imager.getLightness(color)
Get the lightness channel of a color.
# craft.imager.getSaturation(color)
Get the saturation channel of a color.
# craft.imager.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.imager.isLight(color [, threshold=50])
Checks lightness(color) >= threshold. Accepts an optional threshold float as the last parameter with a default of 50.0.
# craft.imager.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.imager.transformImage(image, [{ width: 400 },{ width: 1200 }], { ratio: 16/9 }, { fillTransforms: true }) %}
<img src="{{ craft.imager.placeholder({ width: 16, height: 9 }) }}" sizes="100vw" srcset="{{ transformedImages | srcset }}">