Cropping images in Statamic 6

Before the crop button

Statamic has handled image sizes through Glide for years. Templates ask for a width, a height, or a preset, and Glide generates that version on the fly. Editors influence the result with a focal point: they click the part of the image that matters, and Glide keeps it in frame whenever it has to crop.

That covers most layouts, but not every editor request. If a photo has a stranger at the edge or too much sky, a focal point can't remove it. The image itself has to change.

Craft has shipped an image editor with cropping since version 3 in 2018. In Statamic, the job fell to addons like Image Cropper, a fieldtype that stores a crop per field and leaves the file alone, or to another app: crop it there and upload it again. One request in Statamic's ideas repository describes this routine and asks for simple cropping in the asset view instead.

A crop button in 6.5

Statamic 6.5, released on March 4, delivered exactly that. Jack McDade built the cropper on cropper.js, and it opens from the asset editor. Editors pick an aspect ratio, switch between portrait and landscape, and then either save the result as a new image or replace the original. Which of the two they're offered depends on their permissions: replacing needs permission to reupload the asset, and a new copy needs permission to upload to its container.

In the pull request, someone asked why the cropping didn't go through Glide, since it's already part of the stack. Jason Varga pointed out that Glide and the focal point can already crop when an image is rendered. The difference is where the change ends up. Glide leaves the original alone, and the cropper changes it.

Two follow-ups came straight from the ideas repository. The cropper started with a fixed set of ratios, and someone asked for their own, such as 5:4 or a letter format. Since 6.18 on May 8, the list lives in config/statamic/assets.php:

'crop_aspect_ratios' => [
    '16:9',
    '4:3',
    ['label' => 'Portrait', 'ratio' => '4:5'],
],

Each entry is either a ratio or an array with a label. Developers can limit the list to the ratios the site's templates actually use, so editors don't have to guess which one is right. Five days later, version 6.19 added crop dimensions to the editor. Another request had pointed out how easy it was to end up with an image that's too small for where it's used.

Why the crop moved to the server

The first version cropped in the browser. It drew the image onto a canvas, cut out the selected area, and encoded the result before uploading it. That works, but it re-encodes a file that was already compressed. The browser used a fixed high quality, no matter how the original was saved. In Jason Varga's pull request for 6.22, an 11 MB JPEG came out of the cropper as a 13 MB file. The picture got smaller, and the file got bigger.

Statamic 6.22, released on June 19, changes that. The browser now sends only the crop coordinates, and the server cuts the original with Intervention Image, the library Statamic already uses for image manipulation. The image is encoded once, straight from the source. Before cropping, the server also applies the photo's EXIF orientation, so the preview coordinates line up with the actual pixels.

The save dialog now has two new controls. A quality slider for lossy formats starts at the new crop_quality option in the same config file. If that isn't set, Statamic uses the default quality for image manipulation, and then 90. You can also save the crop in a different format, as long as the container allows that file type. Lowering the quality of a PNG converts it to WebP, which keeps transparency, and converting to JPEG asks whether transparent areas should become black or white. Since a new format means a new file extension, you can only save those crops as a copy.

Focal point or crop

With both tools in the control panel, editors now have two ways to fix an image, and they work very differently. A focal point changes nothing in the file. It tells Glide what matters, and Glide uses that for every size the templates ask for. A crop changes the image itself, and if the editor replaces the original, the cut-off parts are gone. Statamic doesn't keep earlier versions of an asset.

That leads to a fairly simple rule. If an image appears in several sizes and formats, the focal point is the better tool because it adapts to each one. Use a crop for images that are wrong everywhere, like a photo with something at the edge that shouldn't be there. When in doubt, saving a copy costs a little storage and keeps the original.

One gap remains. An asset still has only one focal point, so a hero image that is wide on desktop and tall on mobile can't have a different focus for each. An open request in the ideas repository asks for multiple focal points, and the usual workaround is still to duplicate the image. With the cropper, those duplicates at least no longer need another app.