How Sanity image URLs are built
Every Sanity image URL starts with https://cdn.sanity.io/images/ followed by the project ID, dataset, asset ID, original dimensions and format. Passing a configured Sanity client to the builder presets it with that client's project ID and dataset. The source can be an image object, an asset object or an asset ID string. For how projects and datasets fit into the CMS, see what Sanity is and how it works.
Transformations are defined by chaining builder methods such as width(), height() and blur(). The url() call comes last in the chain and returns the finished URL as a string.
Crop and hotspot are applied only when you pass the full image record and set both width and height. Pass an asset ID alone and the editor's crop does not reach the URL. ignoreImageParams() tells the builder to skip the crop and hotspot stored on the record.
Key features and version notes
Format selection:
auto('format')lets the CDN serve WebP or AVIF to browsers that support them.Readable file names:
vanityName()appends a file name to the end of the URL, which the package README recommends for SEO.Signed URLs: time-limited CDN URLs come from a separate submodule,
@sanity/image-url/signed. Signing must run on the server so the private signing key never reaches client code.Source formats: transformations work on JPEG, PNG, WebP, PJPG, TIFF, AVIF and GIF files only.
Serving the untransformed base image URL directly can push a project into usage overages. Request a sized image instead. Image weight also affects page speed and SEO.
Version 2.0.0 (November 2025) renamed the main export from imageUrlBuilder to createImageUrlBuilder, a breaking change. The release moved utilities and types to named exports without changing what the library does.
The fit setting Pagepro checks
The builder's fit mode decides what happens when the requested size is larger than the source. Modes such as clip, fill and scale upscale a small upload to the requested size, which can turn a tiny source into an image of several megabytes. In its Sanity development work, Pagepro sets fit to max for any field editors upload to, because max never returns an image larger than the original.
Sources
- @sanity/image-url (README)Sanity · github.com
- Presenting imagesSanity · sanity.io
- Image transformationsSanity · sanity.io
- Image URL library v2.0.0: More intuitive exports, better type support, and modernized librarySanity · sanity.io