More control over the img tag

Wagtail provides two shortcuts to give greater control over the img element:

1. Adding attributes to the {% image %} tag

Extra attributes can be specified with the syntax attribute="value":

{% image page.photo width-400 class="foo" id="bar" %}

You can set a more relevant alt attribute this way, overriding the one automatically generated from the title of the image. The src, width, and height attributes can also be overridden, if necessary.

2. Generating the image “as foo” to access individual properties

Wagtail can assign the image data to another variable using Django’s as syntax:

{% image page.photo width-400 as tmp_photo %}

<img src="{{ tmp_photo.url }}" width="{{ tmp_photo.width }}"
    height="{{ tmp_photo.height }}" alt="{{ tmp_photo.alt }}" class="my-custom-class" />

This syntax exposes the underlying image Rendition (tmp_photo) to the developer. A “Rendition” contains the information specific to the way you’ve requested to format the image using the resize-rule, i.e. dimensions and source URL. The following properties are available:

If your site defines a custom image model using AbstractImage, any additional fields you add to an image (e.g. a copyright holder) are not included in the rendition.

Therefore, if you’d added the field author to your AbstractImage in the above example, you’d access it using {{ page.photo.author }} rather than {{ tmp_photo.author }}.

(Due to the links in the database between renditions and their parent image, you could access it as {{ tmp_photo.image.author }}, but that has reduced readability.)

The attrs shortcut

You can also use the attrs property as a shorthand to output the attributes src, width, height and alt in one go:

<img {{ tmp_photo.attrs }} class="my-custom-class" />

Alternative HTML tags

The as keyword allows alternative HTML image tags (such as <picture> or <amp-img>) to be used. For example, to use the <picture> tag:

<picture>
    {% image page.photo width-800 as wide_photo %}
    <source srcset="{{ wide_photo.url }}" media="(min-width: 800px)">
    {% image page.photo width-400 %}
</picture>

And to use the <amp-img> tag (based on the Mountains example from the AMP docs):

{% image image width-550 format-webp as webp_image %}
{% image image width-550 format-jpeg as jpeg_image %}

<amp-img alt="{{ image.alt }}"
    width="{{ webp_image.width }}"
    height="{{ webp_image.height }}"
    src="{{ webp_image.url }}">
    <amp-img alt="{{ image.alt }}"
        fallback
        width="{{ jpeg_image.width }}"
        height="{{ jpeg_image.height }}"
        src="{{ jpeg_image.url }}"></amp-img>
</amp-img>

Images embedded in rich text

The information above relates to images defined via image-specific fields in your model. However, images can also be embedded arbitrarily in Rich Text fields by the page editor (see Rich Text (HTML)).

Images embedded in Rich Text fields can’t be controlled by the template developer as easily. There are no image objects to work with, so the {% image %} template tag can’t be used. Instead, editors can choose from one of a number of image “Formats” at the point of inserting images into their text.

Wagtail comes with three pre-defined image formats, but more can be defined in Python by the developer. These formats are:

For more information about image formats, including creating your own, see Image Formats in the Rich Text Editor

Output image format

Wagtail may automatically change the format of some images when they are resized:

• PNG and JPEG images don’t change format
• GIF images without animation are converted to PNGs
• BMP images are converted to PNGs
• WebP images are converted to PNGs

It is also possible to override the output format on a per-tag basis by using the format filter after the resize rule.

For example, to make the tag always convert the image to a JPEG, use format-jpeg:

{% image page.photo width-400 format-jpeg %}

You may also use format-png or format-gif.

{% image page.photo width-400 format-webp-lossless %}

Background color

The PNG and GIF image formats both support transparency, but if you want to convert images to JPEG format, the transparency will need to be replaced with a solid background color.

By default, Wagtail will set the background to white. But if a white background doesn’t fit your design, you can specify a color using the bgcolor filter.

This filter takes a single argument, which is a CSS 3 or 6 digit hex code representing the color you would like to use:

{# Sets the image background to black #}
{% image page.photo width-400 bgcolor-000 format-jpeg %}

Image quality

Wagtail’s JPEG and WebP image quality settings default to 85 (which is quite high). This can be changed either globally or on a per-tag basis.

# settings.py

# Make low-quality but small images
WAGTAILIMAGES_JPEG_QUALITY = 40
WAGTAILIMAGES_WEBP_QUALITY = 45

# Replace this with your custom rendition model if you use one
>>> from wagtail.images.models import Rendition
>>> Rendition.objects.all().delete()

$ ./manage.py wagtail_update_image_renditions --purge

{% image page.photo_jpeg width-400 jpegquality-40 %}
{% image page.photo_webp width-400 webpquality-50 %}

{% image page.photo width-400 format-jpeg jpegquality-40 %}
{% image page.photo width-400 format-webp webpquality-50 %}