Portable Text Serialization

If you're rendering Sanity's Portable Text in any frontend framework, this covers the component mapping pattern that's consistent across React, Svelte, Vue, Astro, and server-side HTML. The skill breaks down the block structure (marks, markDefs, listItem levels) and shows you how to map custom types like images or code blocks so they actually render instead of disappearing silently. It includes framework-specific rules for each major library, plus a quick reference for community serializers in React Native, PHP, Python, and others. The emphasis on keeping your components object stable and handling missing types explicitly will save you from common re-render bugs and silent failures when content editors add new block types.

skills.sh installs: 3K
GitHub stars: 197
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add sanity-io/agent-toolkit --skill portable-text-serialization --agent claude-code

Installs into .claude/skills of the current project.

Files

Portable Text Serialization

Render Portable Text content across frameworks using the @portabletext/* library family. Each library follows the same component-mapping pattern: you provide a components object that maps PT node types to framework-specific renderers.

Portable Text Structure (Quick Reference)

PT is an array of blocks. Each block has _type, optional style, children (spans), markDefs, listItem, and level.

Root array
├── block (_type: "block")
│   ├── style: "normal" | "h1" | "h2" | "blockquote" | ...
│   ├── children: [span, span, ...]
│   │   └── span: { _type: "span", text: "...", marks: ["strong", "<markDefKey>"] }
│   ├── markDefs: [{ _key, _type: "link", href: "..." }, ...]
│   ├── listItem: "bullet" | "number" (optional)
│   └── level: 1, 2, 3... (optional, for nested lists)
├── custom block (_type: "image" | "code" | any custom type)
└── ...more blocks

Marks come in two forms:

Decorators: string values in marks[] like "strong", "em", "underline", "code"
Annotations: keys in marks[] referencing entries in markDefs[] (e.g., links, internal references)