# Render Sanity images through astro:assets with SanityImage

**Version:** v4.1.0

**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](https://www.sanity.io/docs/astro/images-and-portable-text-astro).

**astro.config.mjs**

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

export default defineConfig({
  image: { service: sanityImageService() },
  integrations: [sanity({ projectId: '<project-id>', dataset: '<dataset>' })],
})
```

**src/pages/posts/[slug].astro**

```html
---
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:

**src/components/ArtDirectedImage.astro**

```html
---
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](https://github.com/sanity-io/sanity-astro/releases/tag/%40sanity%2Fastro%404.1.0).

