Troubleshooting returning image URLs in Next.js using Sanity.io

Ah, I see what you're experiencing! The url property you're seeing in sample code is not automatically returned when you query an image field - you need to explicitly request it by dereferencing the asset reference.

The Issue

When you query an image field in Sanity, you get an asset object with just _ref and _type because that's how Sanity stores image references. The actual image data (including the url) lives in a separate asset document that you need to dereference.

The Solution

To get the image URL in your GROQ query, you need to use the dereference operator (->) to follow the asset reference:

*[_type == "yourDocumentType"]{
  title,
  "imageUrl": image.asset->url
}

For example, if you have a movie document with a poster image:

*[_type == "movie"]{
  title,
  "posterUrl": poster.asset->url
}

For Arrays of Images

If you have an array of images, use the array traversal syntax with []:

*[_type == "movie"]{
  title,
  "imageUrls": images[].asset->url
}

This returns a simple array of URL strings.

Using @sanity/image-url

Alternatively, you can use the @sanity/image-url helper library in your frontend code. This is actually the recommended approach because it gives you access to Sanity's image transformation pipeline:

import imageUrlBuilder from '@sanity/image-url'

const builder = imageUrlBuilder(client)

function urlFor(source) {
  return builder.image(source)
}

// Then use it with your image asset reference:
const imageUrl = urlFor(movie.poster).width(800).url()

With this approach, you just query the image field normally (with the _ref), and construct the URLs with transformations in your frontend.

The key takeaway: the url property requires dereferencing the asset with -> in your GROQ query, or you can construct URLs in your frontend using the @sanity/image-url helper library. The docs you're looking for are the How Queries Work guide (specifically the section on dereferencing) and the Image URLs documentation for the @sanity/image-url package.