How to use hotspot and crop attributes for images in Sanity queries?

36 replies

Last updated: Dec 22, 2021

Hi, I just started with sanity not long ago. I was wondering how I can modify my image from the query using the hotspot and crop attributes from the query. I went through the documentation but it seems that it didn’t work for me.

AI Update

I understand the confusion with hotspot and crop data! The key thing to know is that when you query an image with hotspot/crop data, that data is automatically included in the image object, but how you use it depends on which tool you're working with.

Let me break down the most common scenarios:

Using @sanity/image-url (Image URL Builder)

When you use the image URL builder, the hotspot and crop data are automatically applied when you pass the entire image object to it:

import imageUrlBuilder from '@sanity/image-url'

const builder = imageUrlBuilder(sanityClient)

function urlFor(source) {
  return builder.image(source) // Pass the whole image object
}

// In your GROQ query, just get the image field normally:
// *[_type == "post"][0].mainImage

const imageUrl = urlFor(image)
  .width(400)
  .height(300)
  .url()

The builder will automatically read the hotspot and crop properties from your image object and apply them to the transformations.

Common Issue: Not Passing the Complete Image Object

The most common mistake is only passing the asset reference instead of the entire image object. Make sure your GROQ query includes the full image field:

// ✅ Correct - gets the whole image object including hotspot/crop
*[_type == "post"][0]{
  mainImage
}

// ❌ Wrong - only gets the asset reference
*[_type == "post"][0]{
  "imageUrl": mainImage.asset->url
}

Manual Implementation with CSS

If you're using frameworks like Next.js where the hotspot doesn't seem to work automatically (a common issue), you can manually apply the hotspot using CSS:

function getPositionFromHotspot(hotspot) {
  if (!hotspot || !hotspot.x || !hotspot.y) return "center";
  return `${hotspot.x * 100}% ${hotspot.y * 100}%`;
}

// Usage with Next.js Image
<Image
  src={urlForImage(image).url()}
  alt={image.alt}
  fill
  style={{
    objectFit: 'cover',
    objectPosition: getPositionFromHotspot(image?.hotspot)
  }}
/>

Enabling Hotspot in Your Schema

Make sure hotspot is enabled in your schema first:

{
  name: 'mainImage',
  type: 'image',
  options: {
    hotspot: true  // This enables the hotspot feature
  }
}

What the Hotspot Data Looks Like

When you query an image with hotspot, the data structure looks like this:

{
  _type: 'image',
  asset: { _ref: '...', _type: 'reference' },
  hotspot: {
    x: 0.5,      // 0-1 (percentage from left)
    y: 0.3,      // 0-1 (percentage from top)
    height: 0.4,
    width: 0.4
  },
  crop: {
    top: 0,
    bottom: 0,
    left: 0,
    right: 0
  }
}

The most likely issue you're facing is either not passing the complete image object to the URL builder, or working with a frontend framework that needs the manual CSS approach. If you're using the image URL builder correctly with the full image object, the hotspot should work automatically without any extra code!

Show original thread

36 replies

Hi User. If you’re using JavaScript on your front end, the image builder is the way to go.
1. Import your client and the image-builder and configure a function. This is often done in its own file so that it can be easily imported into any file that uses it (see

sanity.js

).2. Import the function into the file(s) where you need it.

import { urlFor } from '../lib/sanity'

, for example.3. Use the function in your image’s

src

attribute (see

file.js

// lib/sanity.js (could be named whatever you want)
//
// I'm pulling in the dataset and projectId from a .env file

import sanityClient from '@sanity/client';
import imageUrlBuilder from '@sanity/image-url';

export const options = {
  dataset: process.env.NEXT_PUBLIC_SANITY_DATASET_NAME,
  projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID,
  useCdn: process.env.NODE_ENV === 'production',
  apiVersion: '2021-03-25',
};

export const client = sanityClient(options);

export function urlFor(source) {
  const imageBuilder = imageUrlBuilder(client);
  return imageBuilder.image(source);
}

// file.js
//
// However you're pulling in your data, let's assume you've
// destructured so there's an image called image and alt text
// in imageAlt. You can chain image builder methods per the
// docs at <https://www.sanity.io/docs/image-url>

<img
  src={urlFor(image).width(575).fit('max').url()}
  alt={imageAlt}
/>

// ...

The image builder will respect the crops and hotspots that have been set in the studio.

Will the image builder use all the properties from crop and hotspot from sanity ui?

Yes. Edited to add that bit.

Let me try that, thanks. I’ll follow up if I encounter issues

Sounds good! 🙌

Just one thing, to make sure im querying the proper stuff

My current code to query is this:

`*[_type == "post"] | order(publishedAt desc) {
					title,
					slug,
					publishedAt,
					description,
					mainImage {
						asset -> {
							_id,
							url
						},
						crop,
            			hotspot,
						alt
					}
				}`

In that case, I believe

<img src={urlFor(mainImage).url()} alt={mainImage.alt} />

should work (with whatever other methods you want—just put

url()

last).

In that case, I believe

<img src={urlFor(mainImage).url()} … />

should work (with whatever other methods you want—just put

url()

last).

.url() inside the src, right?

Correct.

alright, let me give it a try

And all of this inside of a

.map()

, since your query is returning an array of posts.

oh yeah, i have the map, i managed to get the rest of the data out

i just need to format the image which i couldnt

let me try the image thing

im trying to import urlFor

not sure where should i import it from

It would need to be set up and exported from a file (in my example above, the last 4 lines of

lib/sanity.js

oh so i can copy the example you gave me and put it in my src

You should be able to, yes. You’ll want to install those packages with npm or yarn, and you may need to change the bit where you specify your dataset and projectId, but otherwise it should be copy-and-pasteable.

let me try that 🙂

it doesnt seem to change anything

so heer is the query

`*[slug.current == "${slug}"]{
            title,
            _id,
            slug,
			publishedAt,
			postImage{
                asset->{
                    _id,
                    url
                },
				crop,
				hotspot,
				alt
            },
            mainImage{
                asset->{
                    _id,
                    url
                },
				crop,
				hotspot,
				alt
            },
            body,
            "name": author->name,
            "authorImage": author->image,
        }`

<img
						src={urlFor(singleInsight.postImage.asset.url).url()}
						alt={singleInsight.postImage.alt}
						/>

unless im doing it wrong haha

src={urlFor(singleInsight.postImage.asset.url).url()}

should be just

src={urlFor(singleInsight.postImage).url()}

(or maybe even

src={urlFor(postImage).url()}

i see

yep it worked

thank you so much!

great help man! have a great day

Great! Glad to hear it. Thanks, you too! 🙌

Ah! I think your explanation,

user A

, is what I need. I'm reading the docs about the image builder but it wasn't clear to me where to put the imageBuilder code: in my config file under /lib, in each file or in its own file (somewhere). I think this will get me there. I'm commenting to say thanks for the explanation and to "bookmark" it so I can find it again!
I'm referring to this code:

import React from 'react'

import client from './sanityClient'
import imageUrlBuilder from '@sanity/image-url'

// Get a pre-configured url-builder from your sanity client
const builder = imageUrlBuilder(client)

// Then we like to make a simple function like this that gives the
// builder an image and returns the builder for you to specify additional
// parameters:
function urlFor(source) {
return builder.image(source)
}```

from
https://www.sanity.io/docs/presenting-images#mY9Be3Ph
(And sorry, I can't seem to code block on my tablet!)

Sanity – Build the way you think, not the way your CMS thinks

Sanity is the developer-first content operating system that gives you complete control. Schema-as-code, GROQ queries, and real-time APIs mean no more workarounds or waiting for deployments. Free to start, scale as you grow.

Get started for free Explore the demo