These functions generate Sanity CDN URLs with query parameters for image transformations. They are re-exported from the main sanity-image package for convenience.
Import
import { buildSrc, buildSrcSet } from 'sanity-image'
buildSrc
Converts image parameters into a full CDN URL with computed output dimensions.
Signature
function buildSrc(inputs: ImageSrcInputs): ComputedImageData
Parameters
Image source inputs including base URL and query parameters.type ImageSrcInputs = ImageQueryInputs & { baseUrl: string }
type ImageQueryInputs = {
id: string // Sanity Image ID
mode?: 'cover' | 'contain' // Defaults to 'contain'
width?: number // Target width in pixels
height?: number // Target height in pixels
hotspot?: { x: number; y: number } | null
crop?: CropData | null
queryParams?: DirectQueryParams
}
Returns
Object containing the full URL and computed dimensions.type ComputedImageData = {
src: string // Full URL to the image
width: number // Actual output width in pixels
height: number // Actual output height in pixels
}
Example
const imageData = buildSrc({
id: 'image-abc123-1920x1080-jpg',
baseUrl: 'https://cdn.sanity.io/images/project/dataset/',
width: 800,
height: 600,
mode: 'cover'
})
// Returns:
// {
// src: 'https://cdn.sanity.io/images/project/dataset/abc123-1920x1080.jpg?w=800&h=600&fit=crop&q=75&auto=format',
// width: 800,
// height: 600
// }
buildSrcSet
Generates a responsive srcset string with multiple image sizes for different pixel densities.
Signature
function buildSrcSet(inputs: ImageSrcInputs): string[]
Parameters
Same parameters as buildSrc. The function generates multiple sizes based on the provided width.
Returns
Array of srcset entries in the format <url> <width>w. Multipliers are automatically determined based on the base width:
- Width < 160px:
[0.5, 1, 2]
- Width < 750px:
[0.5, 1, 1.5, 2]
- Width < 1400px:
[0.25, 0.5, 0.75, 1, 1.5, 2]
- Width ≥ 1400px:
[0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]
Entries with width < 50px at multipliers < 1 are excluded. Example
const srcSet = buildSrcSet({
id: 'image-abc123-1920x1080-jpg',
baseUrl: 'https://cdn.sanity.io/images/project/dataset/',
width: 800,
mode: 'contain'
})
// Returns:
// [
// 'https://cdn.sanity.io/images/project/dataset/abc123-1920x1080.jpg?w=200&fit=max&q=75&auto=format 200w',
// 'https://cdn.sanity.io/images/project/dataset/abc123-1920x1080.jpg?w=400&fit=max&q=75&auto=format 400w',
// 'https://cdn.sanity.io/images/project/dataset/abc123-1920x1080.jpg?w=600&fit=max&q=75&auto=format 600w',
// 'https://cdn.sanity.io/images/project/dataset/abc123-1920x1080.jpg?w=800&fit=max&q=75&auto=format 800w',
// 'https://cdn.sanity.io/images/project/dataset/abc123-1920x1080.jpg?w=1200&fit=max&q=75&auto=format 1200w',
// 'https://cdn.sanity.io/images/project/dataset/abc123-1920x1080.jpg?w=1600&fit=max&q=75&auto=format 1600w'
// ]
Usage in HTML
<img
srcSet={buildSrcSet({ ... }).join(', ')}
sizes="(max-width: 768px) 100vw, 800px"
src={buildSrc({ ... }).src}
alt="Responsive image"
/>
Common Types
DirectQueryParams
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 only)
sharp?: number // Sharpen 0-100
}
CropData
type CropData = {
bottom: number // Crop from bottom (0-1)
left: number // Crop from left (0-1)
right: number // Crop from right (0-1)
top: number // Crop from top (0-1)
}
Mode Behavior
contain (default)
- Fits the image within the specified dimensions
- Preserves aspect ratio
- Uses
fit=max query parameter
- Height parameter is converted to width-based constraint
cover
- Crops the image to match the requested aspect ratio
- Uses
fit=crop query parameter
- Respects hotspot for focal point cropping
- Falls back to
crop=entropy if no hotspot provided