Sanity Image Pipeline

Why the Image Pipeline Matters

Images typically account for 50-80% of total page weight, directly impacting Core Web Vitals, SEO rankings, and user engagement. Sanity's image pipeline eliminates the need for external image services or preprocessing by providing a complete solution for image transformation, optimization, and global delivery--all through simple URL parameters.

Unlike traditional CMS platforms that require pre-generating multiple image sizes or integrating third-party CDNs, Sanity handles everything on-demand. Upload high-resolution assets once, and the pipeline automatically serves appropriately sized, optimized versions based on each visitor's device and browser capabilities.

The business value extends beyond technical convenience. By centralizing image management in Sanity, development teams eliminate the overhead of maintaining separate image processing infrastructure. Content editors gain autonomy through intuitive hotspot and crop controls, ensuring images always look their best without developer intervention. The global CDN ensures fast delivery to audiences worldwide, with cached transformations eliminating repeated processing overhead. This combination of reduced maintenance, consistent quality, and optimized performance makes the image pipeline a foundational component of any modern Sanity-powered digital experience.

This guide is part of our Platform Docs series, which covers everything from schema design to GROQ queries for comprehensive content fetching. If you're just getting started with Sanity, our getting started guide provides the foundation you need before diving into image handling.

Understanding Image Assets in Sanity

Before diving into transformations, it's essential to understand how Sanity represents and manages images at a fundamental level. This model enables the flexibility and efficiency that makes the image pipeline so powerful.

The Image Type and Asset Model

In Sanity, images follow a two-part model:

The Image Field - Used in documents or embedded in Portable Text, this contains:

• A reference to the underlying asset
• Optional fields like caption, alt text, and credits
• Crop and hotspot settings defined by editors
• Custom metadata specific to that usage

The Asset Document - Contains the actual image data:

• Original file metadata (dimensions, format, size)
• The actual image file in the CDN
• Asset-level metadata (EXIF, color space, etc.)

This separation means one asset can be referenced by multiple images with different crops, captions, and hotspots. Upload a product photo once, then use it across your site with different aspect ratios for hero banners, thumbnails, and galleries.

Image URL Structure

Every Sanity image URL contains all the information needed to locate and transform the asset. The URL follows a predictable structure that makes it easy to understand and manipulate programmatically.

Diagram showing the components of a Sanity image URL with labeled sections for CDN host, project ID, dataset, asset ID, dimensions, and format.

Image Transformations

The transformation system is the heart of Sanity's image pipeline. Every transformation is specified through URL query parameters, making it trivial to generate optimized images on the fly. The pipeline processes transformations in order: crop → resize → effects.

Basic Resize Operations

The w and h parameters control image dimensions. You can specify either width, height, or both to achieve the desired output size. The fit parameter determines how the pipeline handles aspect ratio preservation when both dimensions are specified.

Width-only examples:

• ?w=800 - Scale to 800px width, maintain aspect ratio
• ?w=400&fit=max - Scale to 400px max, never upscale smaller images

Height-only examples:

• ?h=600 - Scale to 600px height, maintain aspect ratio
• ?h=200 - Create thumbnail from height

Both dimensions examples:

• ?w=800&h=600&fit=clip - Fit within 800x600, no cropping
• ?w=800&h=600&fit=crop - Fill 800x600 by cropping excess
• ?w=400&h=400&fit=crop - Create square crop from center

Crop Operations

The rect parameter allows precise pixel-based cropping: ?rect=left,top,width,height. For example, ?rect=50,50,200,200 crops a 200x200 square starting 50 pixels from the left and top edges.

Effect Operations

Beyond resizing, Sanity supports effects like blur (?blur=100), sharpen (?sharpen=20), grayscale (?sat=-100), and color inversion (?invert=true). These can be combined with resize operations for creative effects like progressive placeholders.

Device Pixel Ratio

For high-DPI displays, use ?dpr=2 or ?dpr=3 to generate images at 2x or 3x resolution. Combined with responsive image patterns, this ensures crisp visuals on retina displays without manual calculations.

As documented in Sanity's image transformation reference, all parameters can be combined to achieve complex transformations in a single request.

Fit Mode Reference

The fit parameter controls how images are handled when you specify dimensions:

Visual comparison of each fit mode applied to the same source image at 400x400 output dimensions. Notice how clip preserves the full image within bounds, crop fills the square by trimming edges, and max prevents upscaling for smaller source images.

When choosing a fit mode, consider your design requirements. Use crop for hero images and cards where you need consistent aspect ratios. Use clip or max for images where preserving the entire original is important. For thumbnails of user-uploaded content, fillmax ensures images are never stretched beyond their original quality.

For detailed specifications on each fit mode, refer to Sanity's image transformation documentation.

Using the @sanity/image-url Builder

For JavaScript/TypeScript projects, the @sanity/image-url package provides a chainable API that generates image URLs while automatically respecting crop and hotspot settings. This approach is more readable and maintainable than manually constructing URLs.

Installation and Setup

Install the package via npm or yarn, then configure the builder with your Sanity client. The builder requires a configured client instance to access your project ID and dataset.

npm install @sanity/image-url

Once installed, create a reusable urlFor function that wraps the builder. This function becomes the central point for all image URL generation in your application, ensuring consistent transformation patterns across your codebase.

The builder automatically applies editor-defined crop settings first, then uses hotspot data for additional cropping when needed. This means your frontend code automatically respects the choices content editors make in Sanity Studio--no additional logic required. For customizing the Studio experience with image-specific tools, see our guide on Sanity Studio customization.

Crop and Hotspot System

Sanity's crop and hotspot feature gives content editors precise control over how images are cropped at different sizes--without requiring developer intervention for every new image.

How It Works

Crop defines a fixed region of the image that should always be used. When an editor sets a crop, only that portion of the image can be displayed. This is useful when you know exactly which part of an image matters.

Hotspot defines a focal point that should be preserved when the image needs additional cropping. This is ideal for images where important content might otherwise be cut off at different aspect ratios--like product photos where the product should always remain visible.

Editor Experience

In Sanity Studio, editors can:

1. Define a crop region by dragging to select the desired area
2. Set a hotspot by clicking to mark the focal point
3. Preview how the image looks at various aspect ratios

The system stores these as fractions (0.0 to 1.0) of the original image dimensions, making them resolution-independent.

Developer Integration

When you pass an image object to the URL builder, it automatically applies crop first, then uses hotspot coordinates to determine the focus area when additional cropping is required. The builder handles all the math--converting fractional coordinates to pixel values based on the requested output size.

This seamless integration means your responsive images always respect editor intent. A hero image with a face in the top-right will keep that face visible whether it's displayed on a desktop wide banner or a mobile device with a 4:3 crop.

For implementation details, see our guide on Sanity Schema Design to learn how to add hotspot and crop fields to your image types.

Asset CDN and Global Distribution

Sanity's asset CDN is a globally-distributed content delivery network that caches images at edge locations worldwide. This architecture provides significant performance benefits without any configuration.

How the CDN Works

1. First Request: Image is processed at the origin and cached at the edge location closest to the visitor
2. Subsequent Requests: Identical URLs are served directly from the nearest edge cache
3. Cache Updates: When assets are replaced, caches are invalidated automatically

Diagram showing Sanity CDN edge locations across North America, Europe, Asia-Pacific, and other regions, with sample latency numbers for each location.

Performance Benefits

• Reduced Latency: Images served from nearby edge locations, not distant origin servers
• Parallel Downloads: Browser can download images from multiple CDN domains
• Automatic Optimization: Each unique transformation is cached after first request

Cache Optimization Strategy

To maximize cache efficiency:

• Use consistent transformation patterns across your site
• Avoid ad-hoc size requests--pre-define common sizes
• The more consistent your URLs, the better your cache hit rate

By establishing 3-5 standard image sizes that work across your responsive breakpoints, you ensure that transformed images are reused across multiple pages. A 400px-wide image for mobile tablets, for instance, gets cached after the first page loads and serves instantly for all subsequent visitors.

For more on connecting Sanity to frontend frameworks, see our Next.js integration guide.

Performance Optimization

Optimizing image delivery is critical for Core Web Vitals, SEO, and user experience. Sanity's pipeline provides everything you need to deliver fast-loading images at scale.

Essential Optimization Techniques

Automatic Format Selection The auto=format parameter is your most important optimization. It automatically serves WebP to browsers that support it, or falls back to JPEG/PNG for older browsers. WebP typically reduces file sizes by 30-50% compared to JPEG at equivalent quality, with no perceptible difference in visual quality.

Quality Tuning The q parameter controls compression quality (0-100). Values of 80-85 typically provide excellent quality with minimal file size. Test with your specific images to find the sweet spot. For photographic content, 80 is often indistinguishable from original. For graphics with text, you may prefer 85-90.

Smart Resizing Always request images at or below their displayed size. A 1920px hero image displayed at 100vw on desktop should still be requested at 1920px width--but thumbnails in a grid should request smaller dimensions, not rely on CSS to scale down a large image.

Preventing Upscaling Use fit=max or fit=fillmax for thumbnails or when displaying user-generated content of unknown sizes. This ensures small images aren't stretched, which would create blurry, unprofessional results.

For teams building high-performance web applications, combining Sanity's image pipeline with comprehensive web development services ensures your entire media strategy is optimized for speed and user experience. As outlined in Sanity's image presentation guide, combining these techniques provides optimal performance without sacrificing visual quality.