@portabletext/react

The recommended pattern for a reusable Portable Text renderer is to use InferValue for the value prop and InferStrictComponents for the components prop. This ensures that if your Sanity schema changes (e.g., a new custom type is added), TypeScript will throw an error until you provide a matching handler.

import type { SanityQueries} from '@sanity/client'
import {createImageUrlBuilder} from '@sanity/image-url'
import {
  PortableText,
  type InferStrictComponents,
  type InferValue,
} from '@portabletext/react'

const builder = createImageUrlBuilder(...)

// Array value type for every Portable Text item shape across all registered queries.
type PortableTextValue = InferValue<SanityQueries[keyof SanityQueries]>

export function CustomPortableText({value}: {value: PortableTextValue}) {
  const components = {
    types: {
      // `value` is fully typed from the inferred image variant.
      image: ({value}) => <img src={builder.image(value).url()} alt={value.alt || ''} />,
    },
  } satisfies InferStrictComponents<PortableTextValue>

  return <PortableText components={components} value={value} />
}

When using InferValue<T>, always feed it query result types, not Sanity schema types. Schema types describe storage, while query results describe the actual data shape (including dereferenced fields).

1. Preferred: Every registered query

Use SanityQueries[keyof SanityQueries] to automatically include every Portable Text shape across all queries. This requires overloadClientMethods in sanity.cli.ts#typegen (on by default).

type PortableTextValue = InferValue<SanityQueries[keyof SanityQueries]>

2. Fallback: Specific named queries

If the union from all queries is too large and slows down type-checking, narrow it to specific query results.

import type {AuthorQueryResult, PostQueryResult} from './sanity.types'
type PortableTextValue = InferValue<AuthorQueryResult | PostQueryResult>

3. Alternative: A scoped mock query

Define a focused GROQ query specifically for type generation to keep the union tight.

import {defineQuery} from 'groq'
const mockQuery = defineQuery(`*[_type in ['author', 'category', 'post']]{ ... }`)
type PortableTextValue = InferValue<SanityQueries[typeof mockQuery]>

You can override default HTML rendering or provide components for custom content types by passing a components object to <PortableText />. The provided components are merged with defaults, so you only need to define what you want to change.

Performance Note: To avoid unnecessary re-renders, ensure the components object maintains referential identity. Do not define it directly inside a component's render body; instead, define it outside the component or wrap it in useMemo.

const myPortableTextComponents = {
  types: {
    image: ({value}) => <img src={value.imageUrl} />,
    callToAction: ({value, isInline}) =>
      isInline ? (
        <a href={value.url}>{value.text}</a>
      ) : (
        <div className="callToAction">{value.text}</div>
      ),
  },

  marks: {
    link: ({children, value}) => {
      const rel = !value.href.startsWith('/') ? 'noreferrer noopener' : undefined
      return (
        <a href={value.href} rel={rel}>
          {children}
        </a>
      )
    },
  },
}

const YourComponent = (props) => {
  return <PortableText value={props.value} components={myPortableTextComponents} />
}

When using Sanity TypeGen, you can use InferComponents<T> to ensure your components object is perfectly typed against your queried data. This provides autocomplete for custom types, marks, and block styles.

import { PortableText, type InferComponents } from '@portabletext/react'
import { createClient } from '@sanity/client'
import { defineQuery } from 'groq'

const client = createClient({ ... })

export default async function Page({ slug }: { slug: string }) {
  const query = defineQuery(`*[_type == "post" && slug.current == $slug][0]{title, content}`)
  const data = await client.fetch(query, { slug })

  const components = {
    types: {
      // custom types are autocompleted and fully typed
    },
  } satisfies InferComponents<typeof data.content>

  return (
    <>
      {Array.isArray(data?.content) && (
        <PortableText components={components} value={data.content} />
      )}
    </>
  )
}