Skip to main content
The SanityImage component is a polymorphic React component that renders optimized images from Sanity’s CDN with automatic URL generation, srcset creation, and responsive image support.

​
Import

import { SanityImage } from 'sanity-image'

​
Props

The SanityImage component accepts all standard HTML <img> attributes plus the following props:

​
Configuration Props

​
projectId
string
The Sanity project ID to use. If preferred, provide baseUrl instead.
​
dataset
string
The Sanity dataset to use. If preferred, provide baseUrl instead.
​
baseUrl
string
The base URL for the Sanity CDN. If not provided, the projectId and dataset props will be used to construct the URL.

​
Image Query Props

​
id
string
required
The Sanity Image ID (_id or _ref field value).
​
mode
'cover' | 'contain'
default:"contain"
Use cover to crop the image to match the requested aspect ratio (based on width and height). Use contain to fit the image to the boundaries provided without altering the aspect ratio.
​
width
number
The target width of the image in pixels. Only used for determining the dimensions of the generated assets, not for layout. Use CSS to specify how the browser should render the image instead.
​
height
number
The target height of the image in pixels. Only used for determining the dimensions of the generated assets, not for layout. Use CSS to specify how the browser should render the image instead.
​
hotspot
{ x: number; y: number } | null
The hotspot coordinates to use for the image. Coordinates are between 0 and 1. Note: hotspot width and height are not used.
​
crop
CropData | null
The crop coordinates to use for the image.
type CropData = {
  bottom: number
  left: number
  right: number
  top: number
}
​
queryParams
DirectQueryParams
Query string params to pass to Sanity’s image CDN directly. Note that this is only a subset of the params supported by the Sanity image CDN.
type DirectQueryParams = {
  blur?: number           // Blur 1-2000
  flip?: 'h' | 'v' | 'hv' // Flip horizontally, vertically, or both
  fm?: 'jpg' | 'pjpg' | 'png' | 'webp' // Convert image format
  q?: number              // Quality 0-100 (defaults to 75)
  sat?: -100              // Saturation (-100 for grayscale)
  sharp?: number          // Sharpen 0-100
}

​
Component Props

​
preview
string
A low-quality image placeholder (LQIP) to display while the full image loads. Used with ImageWithPreview component.

​
HTML Attribute Overrides

​
htmlHeight
number
Passed through to the rendered element as height, overriding the default behavior of setting the height property automatically based on the computed output image dimensions.
​
htmlWidth
number
Passed through to the rendered element as width, overriding the default behavior of setting the width property automatically based on the computed output image dimensions.
​
htmlId
string
Passed through to the rendered element as id. The id prop is used to specify the Sanity Image ID, so this is the only way to set the id attribute on the rendered element.

​
Polymorphic Props

​
as
React.ElementType
Allows rendering as a different element type. Defaults to img. When specified, the component will accept all props valid for that element type.

​
Usage Examples

​
Basic Usage

<SanityImage
  id="image-abc123-1920x1080-jpg"
  baseUrl="https://cdn.sanity.io/images/project/dataset/"
  width={800}
  alt="A beautiful landscape"
/>

​
With Project Configuration

<SanityImage
  id="image-abc123-1920x1080-jpg"
  projectId="your-project-id"
  dataset="production"
  width={800}
  height={600}
  mode="cover"
  alt="A beautiful landscape"
/>

​
With Hotspot and Crop

<SanityImage
  id="image-abc123-1920x1080-jpg"
  baseUrl="https://cdn.sanity.io/images/project/dataset/"
  width={800}
  height={600}
  mode="cover"
  hotspot={{ x: 0.5, y: 0.3 }}
  crop={{ top: 0.1, bottom: 0.1, left: 0, right: 0 }}
  alt="Cropped image with focus point"
/>

​
With Query Parameters

<SanityImage
  id="image-abc123-1920x1080-jpg"
  baseUrl="https://cdn.sanity.io/images/project/dataset/"
  width={800}
  queryParams={{
    blur: 50,
    q: 90,
    fm: 'webp'
  }}
  alt="Blurred high-quality WebP image"
/>

​
Type Definitions

type SanityImageProps<T extends React.ElementType> = FullImageProps & PolymorphicProps<T>

type FullImageProps = BaseImageProps & SanityImageConfigurationProps

type BaseImageProps = SanityImageAttributeOverrideProps &
  SanityImageComponentProps &
  ImageQueryInputs

Build docs developers (and LLMs) love

Get started for freeTalk to us