---
name: Portable Text Serialization
slug: portable-text-serialization
category: Frontend
description: Portable Text Serialization renders and serializes Portable Text to React, Svelte, Vue, Astro, HTML, Markdown, and plain text. Use it when building Portable Text renderers, custom serializers, or troubleshooting marks, blocks, lists, and custom types.
github: "https://github.com/sanity-io/agent-toolkit/tree/main/skills/portable-text-serialization"
language: JavaScript
stars: 181
forks: 28
install: "npx degit https://github.com/sanity-io/agent-toolkit/tree/main/skills/portable-text-serialization ~/.claude/skills/portable-text-serialization"
installs_to: ~/.claude/skills/portable-text-serialization
source_path: skills/portable-text-serialization/SKILL.md
collection_size: 7
category_size: 705
collection_url: "https://dirskills.com/collections/sanity-io/agent-toolkit"
added: 2026-09-07T05:20:16.327Z
last_synced: 2026-09-07T05:20:16.327Z
canonical_url: "https://dirskills.com/skills/portable-text-serialization"
---

# Portable Text Serialization

Portable Text Serialization renders and serializes Portable Text to React, Svelte, Vue, Astro, HTML, Markdown, and plain text. Use it when building Portable Text renderers, custom serializers, or troubleshooting marks, blocks, lists, and custom types.

**Install:**

```bash
npx degit https://github.com/sanity-io/agent-toolkit/tree/main/skills/portable-text-serialization ~/.claude/skills/portable-text-serialization
```

## README

# 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)

## Component Mapping Pattern (All Frameworks)

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

| Key | Renders | Props/Data |
|-----|---------|------------|
| `types` | Custom block/inline types (image, code, CTA) | `value` (the block data) |
| `marks` | Decorators + annotations | `children` + `value` (mark data) |
| `block` | Block styles (h1, normal, blockquote) | `children` |
| `list` | List wrappers (ul, ol) | `children` |
| `listItem` | List items | `children` |
| `hardBreak` | Line breaks within a block | — |

## 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](https://www.portabletext.org/integrations/serializers/) but don't have dedicated rule files:

| Target | Package |
|--------|---------|
| React Native | `@portabletext/react-native-portabletext` |
| React PDF | `@portabletext/react-pdf-portabletext` |
| Solid | `solid-portabletext` |
| Qwik | `portabletext-qwik` |
| Shopify Liquid | `portable-text-to-liquid` |
| PHP | `sanity-php` (SanityBlockContent class) |
| Python | `portabletext-html` |
| C# / .NET | `dotnet-portable-text` |
| Dart / Flutter | `flutter_sanity_portable_text` |

## 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:

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