Crop and fit modes explained, with fill, fit-in and positioned crops

When a photo and its target box have different aspect ratios, something has to give. The service either cuts part of the photo to fill the box, or keeps the whole photo and leaves space. This post walks through each mode in Focal’s URL format with worked numbers, shows which part of the image survives a crop, and matches each mode to the page element it suits.

Three questions for every resize

Every crop or fit mode answers three questions:

• Must the output be exactly the size of the box?
• May the service cut off part of the image?
• If it cuts, which part survives?

Keep those in mind as you read the modes below.

The default mode crops to fill the box

Without a fit mode, Focal returns an image of exactly the requested size. It crops as little as possible to reach that size without changing the aspect ratio. It crops in one direction only, never both.

An 800 by 600 source requested at 400 by 150 has a ratio of 1.33, and the target has a ratio of 2.67. The source is too tall, so Focal crops its height:

height to keep = 800 × 150 ÷ 400 = 300
crop: 800 × 600 → 800 × 300 (150px off the top, 150px off the bottom)
resize: 800 × 300 → 400 × 150

CSS has the same behaviour. MDN describes object-fit: cover as sizing the content to fill the box while keeping its aspect ratio, with anything outside clipped.

This post calls the default mode fill, because the result fills the box. Two other things share the name. CSS object-fit: fill stretches the image to the box, which distorts it when the ratios differ. Focal’s fill() filter pads an image with a colour, as described further down.

Positioned crops choose what survives

When the default mode crops, the alignment segments decide where the cut falls. Focal takes a horizontal alignment of left, center or right, and a vertical alignment of top, middle or bottom. The defaults are center and middle. With left, Focal trims only the right side. With top, it trims only the bottom.

Because Focal crops in one direction, only one of the two alignments matters for a given image. A landscape photo cut into a square loses width, so the horizontal alignment applies. A portrait photo cut into a square loses height, so the vertical alignment applies.

Take a 1000 by 1500 portrait product shot requested at 400 by 400. Focal first crops it to 1000 by 1000, then resizes to 400 by 400. The alignment decides which 500 rows go:

Vertical alignment	Rows removed	Rows kept
top	500 from the bottom	0 to 1000
middle	250 from the top and 250 from the bottom	250 to 1250
bottom	500 from the top	500 to 1500

The alignment follows the size in the URL:

/unsafe/400x400/center/top/products/bottle.jpg

fit-in keeps the whole image

The fit-in option tells Focal not to crop. It scales the image until it fits inside the box. The output matches the box on one side and is smaller on the other. The arithmetic takes the smaller of the two scale factors:

800 × 600 into 300 × 200: scale = min(300/800, 200/600) = 0.333 → 267 × 200
400 × 600 into 300 × 200: scale = min(300/400, 200/600) = 0.333 → 133 × 200

CSS calls this object-fit: contain. MDN notes that the browser letterboxes or pillarboxes the result when the ratios differ.

Two details matter in practice. First, fit-in does not enlarge an image that is already smaller than the box. The upscale() filter changes that. A 300 by 200 source requested at fit-in/600x500 with upscale() comes back as 600 by 400.

Second, the output is smaller than the box on one side unless the ratios match. Focal’s fill() filter pads it to the exact requested size with a colour you name, and places the image in the centre. That combination suits product grids, where the service must not cut off any product and every tile must be the same size.

/unsafe/fit-in/300x300/filters:fill(white)/products/chair.jpg

full-fit-in covers the box without cropping

The full-fit-in option scales by the larger of the two factors instead of the smaller. The result covers the box on both sides, and the service cuts nothing. Here are the two photos from the fit-in section again:

800 × 600 into full-fit-in 300 × 200 → 300 × 225
400 × 600 into full-fit-in 300 × 200 → 300 × 450

This mode suits a page that crops the image itself with object-fit: cover. The file is large enough to cover the box, and the browser decides the final cut at display time.

adaptive-fit-in turns the box to match the image

The adaptive-fit-in option swaps the requested width and height when that gives a better result. Focal swaps them when the image is portrait and the box is landscape, or the other way round. It then fits the image as usual.

Take a 600 by 900 portrait photo and a 300 by 200 box:

fit-in 300 × 200:           scale = min(300/600, 200/900) = 0.222 → 133 × 200
adaptive-fit-in 300 × 200:  box becomes 200 × 300, scale = 0.333 → 200 × 300

The adaptive result has about 2.26 times as many pixels. It suits lightboxes and galleries where the frame can follow the photo’s orientation.

Manual crops take exact coordinates

A manual crop names a rectangle in source pixels, as left x top : right x bottom. Focal applies it before any resize. It suits crops that a person chose, such as a merchandiser picking a detail shot or a user framing a profile photo, with the coordinates stored in your database.

On a 3000 by 2000 photo, 1000x500:2200x1700 keeps a 1200 by 1200 square. A size of 600x600 then scales that square down with no further cropping, because the ratios already match.

/unsafe/1000x500:2200x1700/600x600/products/sofa.jpg

Quick reference

Mode	Output size	Cuts the image	CSS equivalent
Default crop	Exactly the box	Yes, in one direction	object-fit: cover
fit-in	Inside the box	No	object-fit: contain
fit-in with fill()	Exactly the box, padded	No	contain with a background colour
full-fit-in	Covers the box	No	None
adaptive-fit-in	Inside the box, or the box turned	No	None
Manual crop	The rectangle, then the size	Yes, where you choose	None

Crop modes in Focal

Focal supports every mode above. That covers the default crop, positioned crops, fit-in, full-fit-in, adaptive-fit-in, manual crops, and the fill and upscale filters. Focal does not do smart or face-aware cropping, so the alignment segments are how you steer a crop. Set them per image type in your templates, for example top for tall product shots. The Focal docs list each segment in order.

To choose modes for your own catalogue, take one landscape and one portrait product photo. Request both at your grid’s tile size in the default mode, with fit-in and fill(white), and with full-fit-in. Put the six results side by side. The pair where no product loses an edge and both tiles match in size is the mode for your grid.

Sources

• Focal docs, URL API
• MDN, object-fit