Image URL parameters

Who this is for. Developers who have an image path but no template object: in JavaScript, a stylesheet, an email built elsewhere, or a headless front end reading images through the API. After this page you can write an image URL that does what you expect, and recognise the cases where only the template object can.

The template methods build these URLs; the work happens when a browser requests one. The platform then generates that version of the file, caches it, and serves the cached copy from then on.

The URL shape

Every file is served from /files/ followed by its folder path and name in the file manager, as in /files/images/pages/hero.jpg. Spaces and other special characters in names are URL-encoded: /files/images/pages/Homepage%20carousel.jpg.

The extension in the path is the format you want back. To have a JPEG delivered as WebP, change the extension to .webp and name the original's format in f: /files/images/pages/hero.webp?f=jpg. f tells the platform which file to start from; it is never the target.

The parameters

Strategy names through the URL

In a URL, give s the value crop or fit, or leave it out to scale: with one dimension the image keeps its aspect ratio, and with both it takes exactly that box. The template's image object works out the final dimensions from any of the seven strategies before it builds the URL (see Resize strategies), so for any other shape, let a template build the URL with getResized() and hand it on, as shown below. For a fitted size in a hand-written URL, compute it yourself: for a 2:1 image inside a 300 × 300 box, ask for ?w=300&h=150.

Worked URLs

A width-constrained thumbnail, tested on this site:

/files/images/api-sandbox/api-sandbox-figure.png?w=300

A JPEG filled into a carousel slot and delivered as WebP, taken from a live site. It is what getResized(1065, 600, 'fit')->toOptimizedFormat() produced in a template:

/files/images/pages/Homepage%20carousel.webp?w=1065&h=600&s=fit&f=jpg

A PNG logo converted to WebP and not resized, from a live site (file name generalised):

/files/images/pages/1/site-logo.webp?f=png

A fallback image swapped in from JavaScript, from a live site:

A crop with an explicit origin, cutting a 1600 × 600 band that starts 200 pixels down from the top of the original. No template on the sites reviewed sets a crop origin, so this one is illustrative:

/files/images/pages/hero.jpg?w=1600&h=600&s=crop&x=0&y=200

Converting to PNG or WebP

To convert an image, give the URL a .png or .webp target. On this site, /files/images/api-sandbox/api-sandbox-figure.webp?f=png is served as image/webp, converted as asked. Ask for PNG when a consumer needs an image other than WebP.

URL or object?

Inside a template, use the object. It knows the image's real dimensions, so it can work out the missing or fitted side of a resize, honour every strategy, add width and height attributes, skip a resize that would change nothing, and fall back safely when a resize is impossible. A card grid rendered by a template is the typical case.

Outside a template, use the URL. A script that picks a size for the viewport, a stylesheet, or a front end fed by the API has only a path. Build the parameters from a small fixed set of sizes, and stick to fit, crop or a single dimension.

When a template needs to hand a URL to a script, let the object build it and pass the result along:

Keeping the number of versions small

Every distinct combination of parameters is generated and cached as a separate file. URLs that come from your own templates and scripts produce a handful of combinations. A page that builds image URLs from something a visitor controls, such as a query parameter, can produce one per value. So:

• Never pass a visitor's input into w, h or q.
• In scripts, round to a few widths, such as 480, 800, 1200 and 1600, rather than using the exact container width.
• Prefer the automatic picture tag to a hand-written script that requests a size per device; see Picture tags and responsive sources.

When a conversion cannot be done

If no image service can produce the requested version when the file is fetched, the platform delivers the original file under the same URL rather than an error. A .webp URL can therefore serve the original JPEG, and browsers accept it. The response's Content-Type shows the format actually delivered: check it before blaming the browser when an image is not as small as expected. Compression, image services and imported images explains which service handles what.