Happening this week! Hear how Amplitude built a self-serve marketing engine to drive growth 🚀

Image transformations

Reference documentation for image transformations.

The anatomy of the image URL

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/zp7mbokg/production/G3i4emG6B8JnTmGoN0UjgAp8-300x450.jpg

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 (jpg).

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:

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 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.

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

The URL parameters

Gotcha

Small images get scaled up to the width or height you specify. To avoid this use &fit=max.

  • autostring

    Set auto=format to automatically return an image in in the most optimised format supported by the browser as determined by its Accept header. To achieve the same result in a non-browser context, use the fm parameter instead to specify the desired format. I.e. fm=webp.

  • 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=ff00 for red background with no transparency.

  • blurinteger

    Blur 1-2000.

  • cropstring

    Use with fit=crop to specify how cropping is performed:

    top, bottom, left and right: The crop starts from the edge specified. crop=top,left will 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 fp-x and fp-y parameters.

    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 dl but 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 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 bg parameter.

    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 bg parameter.

    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, hv

  • fmstring

    Convert image to jpg, pjpg, png, or webp.

  • 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)

  • 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.

  • 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.

  • min-winteger

    Minimum width. Specifies size limits giving the backend some freedom in picking a size according to the source image aspect ratio.

  • orinteger

    Orientation. Possible values: 0, 90, 180 or 270.Rotate the image in 90 degree increments.

  • 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 image

    top: Number of pixels from the top of the image

    width: Width, in pixels, of the crop from the left value

    height: Height, in pixels, of the crop from the top value

  • satnumber

    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.

Read more

Was this article helpful?