Image transformations
Reference documentation for image transformations.
This article provides a detailed rundown of all the options for transforming images with Sanity. A general introduction to our image pipeline and tools can be found here.
Let's start by dissecting this Sanity image URL:
https://cdn.sanity.io/images/zp7mbokg/production/G3i4emG6B8JnTmGoN0UjgAp8-300x450.jpg
https://cdn.sanity.io/images/is the common base for all Sanity image URLs.zp7mbokgis the project IDproductionis the dataset nameG3i4emG6B8JnTmGoN0UjgAp8is the asset ID and the asset metadata document_id300x450is the width and height of the original imagejpgis the file format of the original asset file
The image URLs can always be found in the asset metadata document referred to in an asset reference. Still, you don't have to fetch this document as the asset document ID contains all the information and represents a stable, documented interface you can trust.
The asset ID corresponding the URLs above looks like this: "image-G3i4emG6B8JnTmGoN0UjgAp8-300x450-jpg". It provides the name, dimensions, and format. Given the project ID and dataset name, you have every piece you need to assemble the URLs without fetching the asset document:
https://cdn.sanity.io/images/<project id>/<dataset name>/<asset name>-<original width>x<original height>.<original file format>
This represents the base URLs. If you fetch this, you will be served the original asset. This potentially uses a lot of bandwidth as content managers should upload full-resolution assets. With the Sanity image pipeline, you can scale, crop, and process images on the fly for you based on URL parameters. E.g. by appending ?h=200 to the base URL, you instruct Sanity to scale the image to be 200 pixels tall:
https://cdn.sanity.io/images/zp7mbokg/production/G3i4emG6B8JnTmGoN0UjgAp8-300x450.jpg?h=200
You can specify any number of parameters. This will extract a rectangle from the image starting at 70 pixels from the left and 20 pixels from the top at a width of 120 pixels and a height of 150 pixels, scale it to 200 pixels tall, and blur it:
https://cdn.sanity.io/images/zp7mbokg/production/G3i4emG6B8JnTmGoN0UjgAp8-300x450.jpg?rect=70,20,120,150&h=200&blur=10
Even though the Sanity image backend is fast, you get a tremendous performance boost if your front end limits the number of sizes and crops you ask for. Sanity will cache the result in the global CDN, and if we see the same URLs again, we serve the same data directly from the edge cache closest to the user.
Gotcha
Non-integer values for parameters expecting integers may cause performance issues or timeouts. It is recommended that you always use integer values when the parameter calls for it (e.g., w and h), including when returning calculated values.
&h=200 - Correct
&h=200.0 - May be problematic
While the Image schema type supports a wide range of image formats, transformations are limited to JPEG, PNG, WebP, PJPG, AVIF, and GIF. For all other formats, you should convert the image to one of the supported file types before performing additional transformations.
Protip
The image pipeline now supports transforming animated GIFs.
Gotcha
Small images get scaled up to the width or height you specify. To avoid this use &fit=max.
autostring
Set
auto=formatto automatically return an image in in the most optimized format supported by the browser as determined by itsAcceptheader. To achieve the same result in a non-browser context, use thefmparameter instead to specify the desired format, for examplefm=webporfm=avif.bgstring
Fill in any transparent areas in the image with a color. The string must be resolve to a valid hexadecimal color (RGB, ARGB, RRGGBB, or AARRGGBB). E.g.
bg=ff00for red background with no transparency.blurinteger
Blur 1-2000.
cropstring
Use with
fit=cropto specify how cropping is performed:top, bottom, left and right: The crop starts from the edge specified.crop=top,leftwill crop the image starting in the top left corner.center: Will crop around the center of the imagefocalpoint: Will crop around the focal point specified using thefp-xandfp-yparameters.entropy: Attempts to preserve the "most important" part of the image by selecting the crop that preserves the most complex part of the image.dlstring
Configures the headers so that opening this link causes the browser to download the image rather than showing it. The browser will suggest to use the file name you provided.
dlRawstring
As
dlbut requests the original file/image asset. Requires authentication.dprnumber
Specifies device pixel ratio scaling factor. From 1 to 3.
fitstring
Affects how the image is handled when you specify target dimensions.
clip: The image is resized to fit within the bounds you specified without cropping or distorting the image.crop: Crops the image to fill the size you specified when you specify bothwandhfill: Likeclip, but any free area not covered by your image is filled with the color specified in thebgparameter.fillmax: Places the image within box you specify, never scaling the image up. If there is excess room in the image, it is filled with the color specified in thebgparameter.max: Fit the image within the box you specify, but never scaling the image up.scale: Scales the image to fit the constraining dimensions exactly. The resulting image will fill the dimensions, and will not maintain the aspect ratio of the input image.min: Resizes and crops the image to match the aspect ratio of the requested width and height. Will not exceed the original width and height of the image.flipstring
Flipping. Flip image horizontally, vertically or both. Possible values:
h,v,hvfmstring
Convert image to
jpg,pjpg,png, orwebp.fp-xcoordinate
Focal Point X. Specify a center point to focus on when cropping the image. Values from 0.0 to 1.0 in fractions of the image dimensions. (See
crop)fp-ycoordinate
Focal Point Y. Specify a center point to focus on when cropping the image. Values from 0.0 to 1.0 in fractions of the image dimensions. (See
crop)frameinteger
The frame of an animated image. The only valid value is
1, which is the first frame.hinteger
Height of the image in pixels. Scales the image to be that tall.
invertboolean
Invert the image.
max-hinteger
Maximum height. Specifies size limits giving the backend some freedom in picking a size according to the source image aspect ratio. This parameter only works when also specifying
fit=crop.max-winteger
Maximum width in the context of image cropping. Specifies size limits giving the backend some freedom in picking a size according to the source image aspect ratio. This parameter only works when also specifying
fit=crop.min-hinteger
Minimum height. Specifies size limits giving the backend some freedom in picking a size according to the source image aspect ratio. This parameter only works when also specifying
fit=crop.min-winteger
Minimum width. Specifies size limits giving the backend some freedom in picking a size according to the source image aspect ratio. This parameter only works when also specifying
fit=crop.orinteger
Orientation. Possible values:
0,90,180or270.Rotate the image in 90 degree increments.padinteger
The number of pixels to pad the image. Applies to both width and height.
qinteger
Quality 0-100. Specify the compression quality (where applicable). Defaults are 75 for JPG and WebP.
rectcoordinates
Crop the image according to the provided coordinate values (
left,top,width,height).left: Number of pixels from the left of the imagetop: Number of pixels from the top of the imagewidth: Width, in pixels, of the crop from theleftvalueheight: Height, in pixels, of the crop from thetopvaluesatnumber
Saturation. Currently the asset pipeline only supports
sat=-100, which renders the image with grayscale colors. Support for more levels of saturation is planned for later.sharpinteger
Sharpen 0-100.
winteger
Width of the image in pixels. Scales the image to be that wide.
Images that have the query parameter auto set to format and are requested from a browser that supports the AVIF format will potentially get an AVIF returned.
There are a few exceptions/quirks:
The first few requests for an AVIF may get the "second best option" (WebP if supported, otherwise PNG/JPG depending on the source image). Subsequent requests will eventually get an AVIF back. This is done to ensure a speedy response, since encoding AVIFs is a slow process.
Image requests made prior to the AVIF rollout may already be cached in our CDN and will not return an AVIF response until they expire/fall out of the cache. In other words: if you are not seeing AVIF images being returned, don't worry — they should eventually return AVIF.
You can use curl to verify the behavior:
# Replace the URL with an actual URL from your project.
# Remember to include `?auto=format`!
curl -sS -I \
-H 'accept: image/avif,image/webp,image/*' \
'https://cdn.sanity.io/images/:projectId/:dataset/:filename?auto=format' \
| grep 'content-type:'On the first request, you will likely see image/webp returned. After waiting 30 seconds, run the same command again, and you should see image/avif. If you don't, wait a little longer and retry. If you still do not see AVIF, ensure that the accept header includes image/avif (before other formats) and that the query parameters includes auto=format.