Render Sanity images through astro:assets with SanityImage
Published: November 17, 2026
@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>, andgetImage()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 withsanityImageService({ hostnames: ['cdn.sanity.io', 'images.example.com'] }). - Fill modes: with
fit="cover"(Astro 5.10 and later) orobject-fit: cover,object-positiondefaults to the hotspot, so the subject stays in frame. queryParams: a new prop that adds image transformation parameters to the URL, for examplequeryParams={{ sat: -100 }}. Every other<Image>prop also works, includingwidths,densities,sizes,quality, andformat.- TypeGen:
InferImageValue,InferStrictImageValue, andisImageWithAssetare re-exported from@sanity/astro/image, and theInfer*types accept stega-branded results.
For the full list of changes, see the @sanity/astro 4.1.0 release on GitHub.