image

The image macro is used to render images on a page. It uses a picture tag that allows to render an array of images of different types any sizes.

Definition

{% image(options, images) %}

Input parameters

options

options parameter represents an object of image properties and attributes and consists of the following fields:

Option key	Type	Default	Required	Description
options.img	object	false	no	Object of attributes for the <img> html tag
options.picture	object	false	no	Object of attributes for the <picture> html tag

options.img

options.img parameter represents an object of <img> html attributes. You can read more about <img> attributes here.

Example of the options.img object:

{
    src: '/path/to/fallback',
    width: 400,
    height: 300,
    alt: 'my alt',
    title: 'my title,
    lazy: true,
    class: 'picture padding-top-big'
}

options.picture

options.picture parameter represents an object of <picture> html attributes. You can read more about <picture> attributes here.

Example of the options.picture object:

{
    class: 'my-class'
}

images

object[] parameter represents an array of image objects consisting of the following properties:

Option key	Type	Default	Required	Description
src	string|object[]	""	yes	Represents the path of the image. It can be either a string or if you want to pass multiple sources you can pass an array of source objects
type	string	""	no	Represents the type of the image. More information about the file types here.
media	string	""	no	Represents the media attribute of the image. More information about the media attribute here.
size	string	""	no	Represents the display density descriptor of the image. More information about the responsiveness of images and density descriptors here.

src

Option key	Type	Default	Required	Description
src.path	string	""	yes	Path to the image
src.size	string	""	no	The display density descriptor of the image. More information about the responsiveness of images and density descriptors here

Example of the images array:

[
    {
        src: '/path/to/file1',
        type: 'image/jpeg'
    },
    {
        src: '/path/to/file1-2x',
        type: 'image/webp',
        size: '2x'
    }
]

Example of the images array with multiple sources and sizes:

[
    {
        src: [
            {
                path: '/path/to/file1',
                size: '2x'
            },
            {
                path: '/path/to/file2',
                size: '1.5x'
            },
            {
                path: '/path/to/file3'
            }
        ],
        type: 'image/webp',
    },
    {
        src: [
            {
                path: '/path/to/file1',
                size: '0.5x'
            },
            {
                path: '/path/to/file2',
            },
            {
                path: '/path/to/file3'
            }
        ],
        type: 'image/png',
    },
]

Example

Example of a webp image

{% from "@macros/image.twig" import image %}

<figure class="webp-image">
    {{
        image({
            img: {
                src: 'path/to/fallback-image.jpg',
                width: 200,
                height: 100,
                alt: 'This is an example of an webp image',
                title: 'Webp image',
            }
        },
        [
            {
                src: '/path/to/webp-image.webp',
                type: 'image/webp'
            },
        ]
    )}}
</figure>

Example

Here is an example of rendering an image set of two images with different pixel density descriptors

{% from "@macros/image.twig" import image %}

<figure>
    {{
        image({
            img: {
                src: 'path/to/fallback-image.jpg',
                width: 300,
                height: 400,
                alt: 'This is an example of an image set',
                title: 'Image set'
            }
        },
        [
            {
                src: [
                    {
                        src: '/path/to/high-quality-image@2x.jpg',
                        size: '2x'
                    }, 
                    {
                        src: '/path/to/low-quality-image@1x.jpg'
                    }
                ],
                type: 'image/jpg'
            },
        ]
    )}}
</figure>

Example

Here is an example of a set of different types of images

{% from "@macros/image.twig" import image %}

<figure class="set-of-images">
    {{
        image({
            img: {
                src: 'path/to/fallback-image.jpg',
                width: 600,
                height: 100,
                alt: 'This is an example of a set of different types of images',
                title: 'Image set',
                class: 'different-types images'
            }
        },
        [
            {
                src: '/path/to/png-image.png',
                type: 'image/png'
            },
            {
                src: '/path/to/svg-image.svg',
                type: 'image/svg'
            },
            {
                src: '/path/to/webp-image.webp',
                type: 'image/webp'
            },
        ]
    )}}
</figure>

Example

Example of rendering a basic image with additional class inside the picture tag

{% from "@macros/image.twig" import image %}

{{
    image({
        img {
            src: 'path/to/my-image.jpg',
            width: 200,
            height: 100,
            alt: 'This is an example of a basic image',
            title: 'Basic image',
        },
        picture: {
            class: 'custom-class-for-picture-tag'
        }

    }
)}}

Macro source code

{% macro image(options, images) %}
    {% set defaultPictureOptions = { class: 'image' } %}
    {% set pictureOptions = defaultPictureOptions|merge(options.picture|default({})) %}

    {% if options.picture.class is defined %}
        {% set pictureOptions = options.picture|merge({ class: "#{defaultPictureOptions.class} #{options.picture.class}" }) %}
    {% endif %}

    <picture
        {% for propName, propValue in pictureOptions %}
            {{ propName }}="{{ propValue }}"
        {% endfor %}
    >
        {% for image in images %}
            {% set srcSet = '' %}

            {% if image.src is iterable %}
                {% for source in image.src %}
                    {% set srcSet = source.path ? srcSet ~ "#{source.path} #{source.size ?: '1x'}, " : srcSet %}
                {% endfor %}
            {% else %}
                {% set srcSet = image.src ? "#{image.src} #{image.size ?: '1x'}" : '' %}
            {% endif %}

            {% if srcSet %}
                <source
                    srcset="{{ srcSet }}"
                    type="{{ image.type }}"
                    {% if image.media %} media="{{ image.media }}" {% endif %}
                >
            {% endif %}
        {% endfor %}

        <img 
            {% for propName, propValue in options.img %}
                {{ propName }}="{{ propValue }}"
            {% endfor %}>
    </picture>
{% endmacro %}