Image accepts image objects and applies the studio crop and hotspot

Published: November 16, 2026

v13.5.0

The Image component from next-sanity/image now takes the image field from your GROQ query, so the crop and hotspot editors set in the studio apply without a urlFor helper or hard-coded dimensions. If a Server Component passes imageLoader to next/image, your build fails after you upgrade until you move that component to the client. next-sanity/image is in alpha.

Action required

  • Who's affected: Server Components that pass imageLoader from next-sanity/image as the loader prop of next/image. The Image component from next-sanity/image isn't affected.
  • What to do: Add 'use client' to the top of the file that renders <NextImage loader={imageLoader} />, or render Image from next-sanity/image instead. See Use the image loader with the next/image component.
  • By when: When you upgrade to 13.5.0. Otherwise next build fails with Error: Functions cannot be passed directly to Client Components unless you explicitly expose it by marking it with "use server".

Mark the loader component as a client component

'use client'

import NextImage from 'next/image'
import { imageLoader } from 'next-sanity/image'

export function CustomImage({ src }: { src: string }) {
  return <NextImage loader={imageLoader} src={src} alt="" width={800} height={600} />
}

What caused it

Before 13.5.0, all of next-sanity/image was a client module, so imageLoader reached next/image as a client reference. In 13.5.0 only the Image component is a client component. imageLoader is now a plain function: you can call it from Server Components, for example with getImageProps, but you can't pass it from a Server Component to a Client Component as a prop.

New features

Pass image fields straight to Image

Pass an image object from a query as src. Image 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, as well as asset IDs and CDN URLs. See Render an image field.

import { Image } from 'next-sanity/image'

<Image
  src={post.mainImage}
  projectId={projectId}
  dataset={dataset}
  width={800}
  height={400}
  alt={post.title ?? ''}
/>

When the query dereferences the asset URL (asset->{url}), you can leave out projectId and dataset.

Leave out width and height

Image infers its dimensions from the URL's w and h parameters, its rect crop, or the original dimensions in the asset filename. Set only one dimension and the other follows the image's aspect ratio, so <Image src={post.mainImage} width={800} alt="" /> renders at the aspect ratio the editor chose. This works for URL strings too. See Leave out the width and height.

Blur placeholders from the image metadata

With placeholder="blur", Image uses the asset's LQIP when the query includes asset->{_id, url, metadata{lqip}}, so you don't need blurDataURL. See Show a blur placeholder.

Improvements

  • fill: When src is an image object with a hotspot, object-position defaults to the hotspot, so object-fit: cover keeps the subject in frame. See Fill a container and keep the hotspot in frame.
  • queryParams: A new prop that adds image transformation parameters to the URL, for example queryParams={{ blur: 50 }}. See Add image transformations.
  • TypeGen: InferImageValue, InferStrictImageValue, and isImageWithAsset are re-exported from next-sanity/image, and the Infer* types accept stega-branded sanityFetch results. See Type image fields with TypeGen.
  • Server Components: imageLoader and isImageWithAsset can be called from Server Components, for example with getImageProps for art-directed <picture> elements. The Image component is also exported from the new next-sanity/image/client-component entry point.
  • Dependencies: next-sanity now depends on @sanity/image-url 2.2, so you only need to install it yourself if you build image URLs directly.

Fixes

  • Image: data: and blob: URLs pass through unchanged and render unoptimized, like in next/image, instead of being corrupted by appended CDN parameters.
  • Image: TypeScript accepts the ref prop, which was already forwarded to the <img> element.
  • Image and imageLoader: Stega-encoded characters are stripped from src, so custom stega.filter setups that encode URLs no longer break image requests.
Sanity logosanity.ioAll Systems Operational© Sanity 2026
Change site theme