Skip to content

Image transformations

Reference documentation for image transformations.

The anatomy of the image URL

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.
  • zp7mbokg is the project ID
  • production is the dataset name
  • G3i4emG6B8JnTmGoN0UjgAp8 is the asset ID and the asset metadata document _id
  • 300x450 is the width and height of the original image
  • jpg is 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 referene. 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

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)

  • frameinteger

    Set frame=1 to return the first frame of an animated image.

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

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

Updated on August 8, 2024

Was this article helpful?