profilsoftware/wagtail-thumbnails

wagtail-thumbnails is a small Python package for sites built with Wagtail, an open-source content management system that runs on top of the Django web framework. The library helps developers serve images in several sizes at once, so that a headless frontend, meaning a separate JavaScript app that pulls data through an API, can pick the right image for the device it is rendering on. It targets projects that use Wagtail 6.3 or newer with Django 4.2 and Django REST Framework. The package adds a building block called ThumbnailBlock that editors can drop into a Wagtail StreamField, which is the area where content authors mix text, images, and other elements. When the page is read through the API, a matching serializer outputs a JSON object for each image: the original source URL, alt text resolved from editor input or the image description, the focal point if one was picked in the Wagtail admin, and a map of responsive variants. The defaults ship four variants named full_hd, large, medium, and small, each rendered as WebP with width, height, and format included in the payload. A settings dictionary called WAGTAIL_THUMBNAILS lets a project change the variant list, pick formats like webp, jpeg, or png, and set per-format quality. The same settings can enforce a minimum source width and height, or these checks can be skipped. Bad configuration values raise an error the first time they are read rather than at request time, which the author presents as a guardrail. There is also a validator pipeline. ThumbnailBlock accepts a list of callables that each receive an image and raise a Django ValidationError if the image fails a check. The default ImageResolutionValidator handles minimum width and height, and projects can add their own functions on top, for example to require landscape orientation. The README also explains how to migrate from the older ImageChooserBlock to the new ThumbnailBlock with a one-time data migration. The project is published on PyPI and is MIT licensed.