How to use Sanity image hotspot cropping in Next.js?

The hotspot feature in Sanity Studio doesn't automatically apply to your Next.js frontend - you need to implement it yourself, either using @sanity/image-url or manually with CSS object-position.

Using @sanity/image-url (Recommended)

When you query your image data from Sanity, the hotspot information is included in the image object. The @sanity/image-url builder will automatically respect the hotspot when you apply transformations:

import imageUrlBuilder from '@sanity/image-url'

const builder = imageUrlBuilder(sanityClient)

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

// The builder automatically uses the hotspot data
const imageUrl = urlFor(image)
  .width(400)
  .height(300)
  .url()

Manual CSS Implementation

If the image URL builder doesn't fully respect the hotspot in your setup (which can happen with certain frameworks), you can manually apply it using CSS object-position. The hotspot data contains x and y values between 0-1 representing the focal point as a percentage:

// Helper function to convert hotspot to CSS object-position
function getPositionFromHotspot(hotspot) {
  if (!hotspot || !hotspot.x || !hotspot.y) return "center";
  
  return `${hotspot.x * 100}% ${hotspot.y * 100}%`;
}

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

Enabling Hotspot in Your Schema

Make sure you've enabled hotspot in your schema definition:

{
  name: 'image',
  title: 'Image',
  type: 'image',
  options: {
    hotspot: true
  }
}

As of Studio v3.86.0, you can even configure custom aspect ratio previews to help editors see how their hotspot will work at different sizes.

The key is that yes, it's essentially object-position under the hood, but the values come from the hotspot data you've set in Sanity Studio rather than being hardcoded in your CSS.