Skip to main content
Follow these steps to start using Sanity Image in your React application.
1

Install the package

Add sanity-image to your project using your preferred package manager:
npm install sanity-image
Sanity Image requires React 18+ or 19+ as a peer dependency.
2

Get your Sanity project details

You’ll need your Sanity project ID and dataset name. Find these in your Sanity project settings, or construct your base URL:
https://cdn.sanity.io/images/{projectId}/{dataset}/
For example: https://cdn.sanity.io/images/abcd1234/production/
3

Import and use the component

The simplest way to use Sanity Image is to pass the image ID, base URL, and alt text:
import { SanityImage } from "sanity-image"

const YourComponent = ({ image }) => (
  <SanityImage
    id={image._id}
    baseUrl="https://cdn.sanity.io/images/abcd1234/production/"
    alt="Demo image"
  />
)
This will render the image at half its original width with an automatically generated srcSet.
4

Add size and mode options (optional)

For more control, specify the expected display dimensions and mode:
<SanityImage
  id={image._id}
  baseUrl="https://cdn.sanity.io/images/abcd1234/production/"
  width={500}
  height={250}
  mode="cover"
  alt="Demo image"
/>
Use mode="cover" to crop the image to fit the aspect ratio, or mode="contain" (default) to fit within the boundaries without cropping.
5

Fetch image data from Sanity (optional)

To get the most out of Sanity Image, fetch hotspot, crop, and preview data from Sanity using GROQ:
*[_type == "post"] {
  title,
  mainImage {
    "id": asset._ref,
    "preview": asset->metadata.lqip,
    hotspot { x, y },
    crop { bottom, left, right, top }
  }
}
Then use this data in your component:
<SanityImage
  id={image.id}
  baseUrl="https://cdn.sanity.io/images/abcd1234/production/"
  width={500}
  height={250}
  mode="cover"
  hotspot={image.hotspot}
  crop={image.crop}
  preview={image.preview}
  alt="Demo image"
/>

​
Expected output

Sanity Image renders a single <img> tag with automatically calculated dimensions and a responsive srcSet: 
<img
  src="https://cdn.sanity.io/images/abcd1234/production/image-abc123-1200x800-jpg.jpg?w=500&h=250&fit=crop&auto=format"
  srcset="https://cdn.sanity.io/images/.../image-abc123...jpg?w=500... 500w,
          https://cdn.sanity.io/images/.../image-abc123...jpg?w=750... 750w,
          https://cdn.sanity.io/images/.../image-abc123...jpg?w=1000... 1000w"
  width="500"
  height="250"
  alt="Demo image"
  loading="lazy"
/>
The component automatically:
  • Generates a srcSet with optimal multipliers based on image size
  • Sets width and height attributes to prevent layout shifts
  • Applies loading="lazy" for native lazy loading
  • Uses auto=format to serve AVIF when supported
Here’s a complete example showing all the main features: 
import { SanityImage } from "sanity-image"

export const BlogPost = ({ post }) => (
  <article>
    <SanityImage
      // Image identification
      id={post.mainImage.id}
      baseUrl="https://cdn.sanity.io/images/abcd1234/production/"
      
      // Display dimensions
      width={800}
      height={400}
      mode="cover"
      
      // Sanity data
      hotspot={post.mainImage.hotspot}
      crop={post.mainImage.crop}
      preview={post.mainImage.preview}
      
      // Image optimization
      queryParams={{ q: 80 }}
      
      // HTML attributes
      alt={post.mainImage.alt}
      className="blog-hero"
      sizes="(min-width: 800px) 800px, 100vw"
      loading="eager"
    />
    
    <h1>{post.title}</h1>
    <div>{post.content}</div>
  </article>
)

​
Next steps

Cover vs Contain Modes

Learn when to use cover or contain mode

Styling Images

Best practices for responsive image styling

Create a Wrapper

Simplify usage with a custom wrapper component

API Reference

Explore all available props and options

Build docs developers (and LLMs) love

Get started for freeTalk to us