How-to library · Developer docs

How-to library

Task-shaped pages: a title that starts with a verb, the situation in a few lines, the steps, the working code in both engines, and why this way rather than another. Found from a search, done, and left.

How-to Images

Choose between the seven resize strategies

Published

auto scales to fit inside a box; fit fills it and crops (despite the name); crop cuts a region unscaled; exact and square stretch; landscape derives the height; for a portrait result, use auto with only a height. Decide from what the slot must guarantee.

Context

Context. getResized(width, height, strategy) takes one of seven strategies: fit is the one that crops, not crop. Decide from what the slot must guarantee. All examples start from a 1200 × 800 landscape photo.

Steps

  1. The slot has a fixed box and must be filled edge to edge (cards, banners, thumbnails): fit, both dimensions. Gives 600 × 600 of the centre, like object-fit: cover.
  2. The whole image must be visible inside a box (logos, product shots): auto with both dimensions. Scales to fit without cropping: 600 × 400 from a 600 × 600 box.
  3. Only one dimension matters (a column width, a row height): auto with one dimension, or landscape with a width. getResized(null, 200) gives 300 × 200.
  4. A detail at native pixels (a zoomed region): crop, both dimensions; the origin can only be set through the URL form.
  5. Never: exact and square stretch the image; portrait raises an error unless a width is also passed and then ignores it, so use auto with only a height instead.

Template code

Template code 
{$image->getResized(600, 600, 'fit')}         {* 600 × 600, cropped to the centre *}
{$image->getResized(600, 600)}                {* auto: 600 × 400, nothing cropped *}
{$image->getResized(600, null, 'landscape')}  {* 600 × 400 *}
{$image->getResized(null, 600)}               {* 900 × 600, the portrait case done safely *}
{$image->getResized(600, 600, 'crop')}        {* a 600 × 600 detail at original scale *}
{{ image.getResized(600, 600, 'fit') }}
{{ image.getResized(600, 600) }}
{{ image.getResized(600, null, 'landscape') }}
{{ image.getResized(null, 600) }}
{{ image.getResized(600, 600, 'crop') }}

Why this and not that

Not CSS alone: object-fit hides the overflow but the browser still downloads the full file; the strategy decides what is generated and sent. Not square for a square crop: it stretches; use fit with equal sides. Resize before converting: a call that cannot be completed (fit with one dimension, an unknown strategy) then falls back to the full-size original and logs it.

Go deeper
GuideResizing, converting and rendering an image GuideImage URL parameters

Was this page helpful?

Your answer goes to the docs team.