Render Sanity images through astro:assets with SanityImage

Published: November 17, 2026

v4.1.0

@sanity/astro 4.1.0 adds <SanityImage>, which takes the image field from your GROQ query and renders it from the Sanity Image CDN through astro:assets. The crop and hotspot editors set in the studio apply without a urlFor helper or hard-coded dimensions. The image API is opt-in and needs Astro 5 or later. Upgrading doesn’t require code changes.

New features

Render image fields with <SanityImage>

Register sanityImageService() as the image service, then pass an image object from a query as src. <SanityImage> builds the CDN URL, applies the studio crop, and positions the crop around the hotspot when the aspect ratio you request differs. src accepts the shapes sanity typegen generates, stega-encoded values, asset documents and references, asset IDs, and CDN URLs. The project ID and dataset come from the integration config. See Render Sanity images.

import sanity, { sanityImageService } from '@sanity/astro'
import { defineConfig } from 'astro/config'

export default defineConfig({
  image: { service: sanityImageService() },
  integrations: [sanity({ projectId: '<project-id>', dataset: '<dataset>' })],
})
---
import { isImageWithAsset, SanityImage } from '@sanity/astro/image'
import { sanityClient } from 'sanity:client'

const post = await sanityClient.fetch(
  `*[_type == "post" && slug.current == $slug][0]{
    title,
    mainImage{ crop, hotspot, alt, asset->{ url, metadata { lqip } } }
  }`,
  { slug: Astro.params.slug },
)
---

{isImageWithAsset(post.mainImage) && (
  <SanityImage
    src={post.mainImage}
    alt={post.mainImage.alt ?? ''}
    width={1200}
    height={630}
    placeholder="blur"
  />
)}

Leave out width and height

<SanityImage> infers missing dimensions from the crop, from the other dimension, or from the original dimensions in the asset filename, without a request to measure the image. Set only width and the height follows the aspect ratio the editor chose.

Blur placeholders from the image metadata

With placeholder="blur", <SanityImage> uses the asset’s LQIP when the query includes asset->{url, metadata{lqip}}, so you don’t need blurDataURL.

Art direction with <Picture> and getImage()

getSanityImageProps() returns the src, width, height, and style that <SanityImage> passes on, so you can use Sanity images with <Picture> and getImage(). For art direction, build one image per breakpoint:

---
import { getImage } from 'astro:assets'
import { getSanityImageProps } from '@sanity/astro/image'

const { image } = Astro.props
const wide = await getImage({
  ...getSanityImageProps(image, { width: 1600, height: 900 }),
  widths: [800, 1600],
})
const tall = await getImage(getSanityImageProps(image, { width: 800, height: 1000 }))
---

<picture>
  <source media="(min-width: 768px)" srcset={wide.srcSet.attribute} />
  <img src={tall.src} {...tall.attributes} alt="" />
</picture>

Improvements

  • Image service: sanityImageService() only handles Sanity CDN URLs and leaves every other image to Astro’s default sharp service. Astro’s own <Image>, <Picture>, and getImage() also get CDN URLs when given a Sanity image URL, so static builds don’t download and reprocess Sanity images. Add a custom CDN domain with sanityImageService({ hostnames: ['cdn.sanity.io', 'images.example.com'] }).
  • Fill modes: with fit="cover" (Astro 5.10 and later) or object-fit: cover, object-position defaults to the hotspot, so the subject stays in frame.
  • queryParams: a new prop that adds image transformation parameters to the URL, for example queryParams={{ sat: -100 }}. Every other <Image> prop also works, including widths, densities, sizes, quality, and format.
  • TypeGen: InferImageValue, InferStrictImageValue, and isImageWithAsset are re-exported from @sanity/astro/image, and the Infer* types accept stega-branded results.

For the full list of changes, see the @sanity/astro 4.1.0 release on GitHub.

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