This article is a detailed rundown of all the options for transforming images with Sanity. You can find a general introduction to our image pipeline and tools here.
Let's start by dissecting this Sanity image-url:
https://cdn.sanity.io/images/ is the common base for all Sanity image URLs. It is followed by the project id (
zp7mbokg in this instance), the dataset (
production) and then the asset id which is comprised of a name (
G3i4emG6B8JnTmGoN0UjgAp8) a dash then the width and height of the original image (
300x450) and the file format of the original image (
The image URLs can always be found in the asset-document referred to by an image, but you don't actually 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". As you can see 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>
So this represents the base URLs. If you fetch this you will be served the original asset. This wastes a lot of bandwidth as content managers should upload full resolution assets. The Sanity image pipeline therefore scales, crops and processes images on the fly for you based on the URL-parameters your provide. E.g. by appending
?h=200 to the base URLs you instruct Sanity to scale the image to be 200 pixels tall:
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:
Even though the Sanity image backend is fast, you get a tremendous performance boost if your frontend 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 exact same data directly from the edge cache closest the the user.
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.,
h), including when returning calculated values.
&h=200 - Correct
&h=200.0 - May be problematic
Small images get scaled up to the width or height you specify. To avoid this use
auto=formatto automatically return an image in in the most optimised format supported by the browser as determined by its
Acceptheader. To achieve the same result in a non-browser context, use the
fmparameter instead to specify the desired format. I.e.
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.
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 image
focalpoint: Will crop around the focal point specified using the
entropy: Attempts to preserve the "most important" part of the image by selecting the crop that preserves the most complex part of the image.
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.
dlbut requests the original file/image asset. Requires authentication.
Specifies device pixel ratio scaling factor. From 1 to 3.
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 both w and h
fill: Like clip, but the any free area not covered by your image is filled with the color specified in the
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 the
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.
Flipping. Flip image horizontally, vertically or both. Possible values:
Convert image to
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
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
Height of the image in pixels. Scales the image to be that tall.
Invert the image.
Maximum height. Specifies size limits giving the backend some freedom in picking a size according to the source image aspect ratio.
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
Minimum height. Specifies size limits giving the backend some freedom in picking a size according to the source image aspect ratio.
Minimum width. Specifies size limits giving the backend some freedom in picking a size according to the source image aspect ratio.
Orientation. Possible values:
270.Rotate the image in 90 degree increments.
Quality 0-100. Specify the compression quality (where applicable). Defaults are 75 for JPG and WebP.
Crop the image according to the provided coordinate values (
left: Number of pixels from the left of the image
top: Number of pixels from the top of the image
width: Width, in pixels, of the crop from the
height: Height, in pixels, of the crop from the
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.
Width of the image in pixels. Scales the image to be that wide.