Pass TypeGen image results to the URL builder without casts

Published: November 16, 2026

v2.2.0

@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 usual Unable to resolve image URL from source error instead of TypeError: 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,NaN in 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.

Sanity logosanity.ioAll Systems Operational© Sanity 2026
Change site theme