Images & Portable Text

A GROQ query hands you raw JSON. But two kinds of content can't just be dropped into JSX and called done — images and rich text. An image from Sanity isn't a URL; it's an asset reference plus a focal point and crop. Rich text isn't a string; it's a tree of typed blocks called Portable Text. Both need a translation layer between "what Sanity stores" and "what the browser renders."

This page covers both layers. They share a theme: the query has to project the right shape, or the renderer quietly gives you nothing. Get the projection right and the rest is mechanical.

Why an image needs more than a URL

When an editor uploads an image in the Studio and drags the little circle to pick a focal point, Sanity stores three things: a reference to the asset (the actual file), a hotspot (the focal point, as fractions), and a crop (how much to trim off each edge). The CDN can honor all of that — serve a 640px-wide WebP cropped around the editor's chosen face — but only if your code passes it the whole object.

That's why every image projection across the codebase looks identical. Copy it verbatim so the frontend always gets the URL, the blur placeholder, the dimensions, and the crop data:

mainImage{
  asset->{
    _id,
    url,
    metadata {
      dimensions { width, height, aspectRatio },
      lqip,
      palette { background, foreground }
    }
  },
  hotspot,
  crop
}

Each piece earns its place. asset->{ url } is the CDN URL the builder transforms. metadata.lqip is a base64 blur shown while the full image loads. metadata.dimensions lets the <img> reserve space and avoid layout shift. And crucially, hotspot / crop stay on the image object, not the asset — because that's where the builder looks for them.

The TypeScript shape that mirrors this projection lives in one place and is imported app-wide — by the helpers, by OptimizedImage, by every DTO with an image field. For any new image field, import ImageAsset rather than redefining it:

export type ImageAsset = {
  asset?: { _id?: string; url?: string; metadata?: ImageMetadata };
  hotspot?: { x?: number; y?: number; width?: number; height?: number };
  crop?: { top?: number; bottom?: number; left?: number; right?: number };
};

Building image URLs in one place

All urlFor-style URL building lives in exactly one file: app/helpers/optimize-sanity-image.ts. It creates the builder once from the shared client, then exposes a handful of helpers. Nothing else in the app touches @sanity/image-url directly.

The core helper takes an ImageAsset and an options bag, then chains the builder. The detail that matters most is on the first builder line:

const builder = imageUrlBuilder(sanityClient);

export function optimizeSanityImage(image, options = {}): string {
  if (!image?.asset?.url) return ""; // short-circuit when the projection is incomplete

  let urlBuilder = builder.image(image); // pass the WHOLE image, not just the url
  if (options.width) urlBuilder = urlBuilder.width(options.width);
  if (options.auto) urlBuilder = urlBuilder.auto(options.auto); // "format" -> WebP/AVIF
  /* ...height, quality, format, fit, blur, dpr applied the same way */
  return urlBuilder.url();
}

Three companion helpers round it out. You rarely call them by hand — OptimizedImage composes all four — but knowing what they return helps when you need a raw value:

The responsive widths come from a shared IMAGE_SIZES constant (mobile: 640 through ultrawide: 1920), so every image on the site uses the same breakpoints — which means the CDN caches them once and serves them everywhere.

Render with OptimizedImage, not the builder

Here's the rule: components almost never call the builder directly. They render <OptimizedImage> (app/components/ui/optimized-image.tsx), which stitches all four helpers into a final <img srcSet sizes width height loading> with an LQIP blur sitting behind it. You hand it a Sanity ImageAsset and a few props; it handles format conversion, responsive sources, dimensions, and the blur-up.

import { OptimizedImage } from "@/components/ui/optimized-image";
import { IMAGE_SIZES } from "@/helpers/optimize-sanity-image";

<OptimizedImage
  image={heroImage}        // a Sanity ImageAsset straight from a query
  alt="Students on campus"
  width={IMAGE_SIZES.wide}
  priority
  loading="eager"
/>;

For an above-the-fold hero, pass priority and loading="eager"; for anything below the fold, the default lazy loading is what you want. There's a full prop list (fillContainer, objectFit, sizes, custom srcSetWidths) in Components.

Portable Text: rich text as a tree, not a string

The other shape that can't go straight into JSX is block content — the rich-text body of a blog post. Sanity stores it as Portable Text: an array of typed blocks (paragraphs, headings, lists, embedded images), each with marks for bold, links, and so on. You render it with @portabletext/react's <PortableText>, which walks that tree and turns each block into an element.

The only place the site renders Portable Text is the blog post route, app/routes/blog-post.tsx — so if you're looking for a working example, that's the file.

Step 1: Project the body, including inline images

Before you can render it, the query has to project the body array. The subtlety is embedded images: a body can contain image blocks, and those need the same full asset metadata as any other image. So the projection spreads everything, then conditionally adds the asset projection only to image blocks:

body[]{
  ...,
  _type == "image" => {
    ...,
    asset->{
      _id,
      url,
      metadata { dimensions { width, height, aspectRatio }, lqip, palette { background, foreground } }
    }
  }
}

The _type == "image" => { ... } is a conditional projection — it touches only image blocks and leaves text blocks alone. Skip it, and inline images in a post lose their URL and render as blank, exactly like a top-level image with a missing projection.

Step 2: Map block types to components

<PortableText> needs to know how to render each block type. You give it a PortableTextComponents map. In this app the map is declared inside the component, because the heading overrides close over the post body and a table-of-contents helper:

import { PortableText, type PortableTextComponents } from "@portabletext/react";
import { OptimizedImage } from "@/components/ui/optimized-image";
import { IMAGE_SIZES } from "@/helpers/optimize-sanity-image";

const portableTextComponents: PortableTextComponents = {
  block: {
    h2: ({ children, value }) => {
      const index = blogPost.body.findIndex((b) => b._key === value._key);
      const headingId = `section-${index}`;
      return (
        <h2 id={headingId} ref={(ref) => addSectionRef(headingId, ref)}>
          {children}
        </h2>
      );
    },
    /* h3 follows the same pattern */
  },
  types: {
    image: ({ value }) => {
      if (!value?.asset) return null;
      return (
        <OptimizedImage
          alt={value.alt || "Blog post image"}
          image={value}
          loading="lazy"
          width={IMAGE_SIZES.desktop}
        />
      );
    },
  },
};

Two override groups carry the weight. The block.h2 / block.h3 overrides add id="section-N" anchors and register a ref so the table of contents can scroll to each heading. The types.image override routes inline images through the same <OptimizedImage> you met above — so a picture embedded mid-article gets the identical WebP, srcSet, and blur treatment as a hero. Note the value.alt || "Blog post image" fallback: defaults live in JavaScript, never in GROQ.

Step 3: Render inside a prose container

Finally, render <PortableText> inside a Tailwind Typography prose wrapper. That's what styles the headings, lists, and paragraphs the renderer emits — without it you'd get unstyled HTML:

<article className="prose prose-lg dark:prose-invert my-8 max-w-none">
  <PortableText components={portableTextComponents} value={blogPost.body} />
</article>

The shape that ties it together

Both halves of this page reduce to one habit: the projection determines whether rendering works. An image with no asset->{ url } is blank. A body without the conditional image projection drops its inline pictures. The renderers don't complain — they just produce nothing — so the fix is always to check the query first.

Where to go next