Pass TypeGen image results to the URL builder without casts
Published: November 16, 2026
@sanity/image-url now accepts every image shape Sanity TypeGen generates, so images from typed query results go straight into builder.image() and your own image helpers. If you use TypeGen with image fields, upgrade to drop your casts. Upgrading doesn't require code changes.
New features
Use TypeGen image types without casts
Raw image fields, images with asset-> dereferenced, partial projections like asset->{_id, url}, and custom image types with extra fields like alt all go into image() without a cast. The new SanityImageLike and SanityImageAssetLike types describe these shapes and are part of SanityImageSource, so helpers typed with SanityImageSource accept them too. Existing types are unchanged.
import { defineQuery } from 'groq'
import { isImageWithAsset } from '@sanity/image-url'
import { client } from './client'
import { urlFor } from './sanityImageUrl'
const POST_QUERY = defineQuery(`*[_type == "post" && slug.current == $slug][0]{
title,
cover,
"figure": figure{alt, asset->{_id, url}}
}`)
const post = await client.fetch(POST_QUERY, { slug: 'hello-world' })
// `cover` is null when the field is unset, and has no asset until an image is uploaded
if (isImageWithAsset(post?.cover)) {
console.log(urlFor(post.cover).width(800).url())
}
// Projections that dereference the asset work too
if (post?.figure) {
console.log(urlFor(post.figure).width(800).url())
}Learn more in Build URLs from TypeGen query results.
Type a shared image component from your queries
InferImageValue<SanityQueries[keyof SanityQueries]> gives a shared image component a value type that covers every image in your TypeGen-registered queries. InferStrictImageValue keeps only the variants that have an asset, and the isImageWithAsset() guard narrows a value to one with an asset at runtime.
import type { SanityQueries } from '@sanity/client'
import { isImageWithAsset, type InferImageValue } from '@sanity/image-url'
import { urlFor } from './sanityImageUrl'
// Every image shape returned by your TypeGen-registered queries
type ImageValue = InferImageValue<SanityQueries[keyof SanityQueries]>
export function SanityImage({ value, width }: { value: ImageValue; width: number }) {
if (!isImageWithAsset(value)) return null
return (
<img
src={urlFor(value).width(width).url()}
alt={('alt' in value && value.alt) || ''}
/>
)
}Fixes
- An image field with no uploaded asset, queried with
asset->, now throws the usualUnable to resolve image URL from sourceerror instead ofTypeError: Cannot read properties of null. - Crop or hotspot data with missing coordinates now falls back to the default value for each missing field, instead of putting
rect=NaN,NaN,NaN,NaNin the URL. Complete crop and hotspot data produces the same URLs as before.
For the full list of changes, see the 2.2.0 release on GitHub.