Portable Text Serialization

Component Mapping Pattern (All Frameworks)

Every @portabletext/* library accepts a components object with these keys:

Framework-Specific Rules

Read the rule file matching your framework:

• React / Next.js: rules/react.md — @portabletext/react or next-sanity
• Svelte / SvelteKit: rules/svelte.md — @portabletext/svelte
• Vue / Nuxt: rules/vue.md — @portabletext/vue
• Astro: rules/astro.md — astro-portabletext
• HTML (server-side): rules/html.md — @portabletext/to-html
• Markdown: rules/markdown.md — @portabletext/markdown
• Plain text extraction: rules/plain-text.md — @portabletext/toolkit

Additional Community Serializers

These are listed on portabletext.org but don't have dedicated rule files:

Common Patterns (All Frameworks)

Custom Types Need Explicit Components

PT renderers only handle standard blocks by default. Custom types (image, code, callToAction, etc.) require explicit component mappings — they won't render otherwise.

Keep Components Object Stable

In React/Vue, define components outside the render function or memoize it. Recreating on every render causes unnecessary re-renders.

Handle Missing Components Gracefully

All libraries accept onMissingComponent to control behavior when encountering unknown types:

• false — suppress warnings
• Custom function — log or report

Querying PT with GROQ

Always expand references inside custom blocks:

body[]{
  ...,
  _type == "image" => {
    ...,
    asset->
  },
  markDefs[]{
    ...,
    _type == "internalLink" => {
      ...,
      "slug": @.reference->slug.current
    }
  }
}