Examples for writing good serializers for React?
I totally get it—serializers can be confusing at first! The package readme can be a bit terse. Let me break it down with some practical examples.
The @portabletext/react package uses a "components" prop (they call them serializers/components interchangeably) to customize how different parts of your Portable Text render. Here's the key thing to understand: the structure of your components object mirrors the structure of your Portable Text.
Basic Structure
import {PortableText} from '@portabletext/react'
const components = {
types: {
// Custom block types (images, code blocks, etc.)
},
marks: {
// Inline formatting (bold, links, highlights, etc.)
},
block: {
// Paragraph styles and headings
},
list: {
// Bullet and numbered lists
}
}
<PortableText value={portableTextContent} components={components} />Practical Examples
Custom headings and paragraphs:
const components = {
block: {
h1: ({children}) => <h1 className="text-4xl font-bold">{children}</h1>,
h2: ({children}) => <h2 className="text-3xl">{children}</h2>,
normal: ({children}) => <p className="my-4">{children}</p>
}
}Custom marks (inline formatting):
const components = {
marks: {
link: ({value, children}) => {
const target = value?.href?.startsWith('http') ? '_blank' : undefined
return <a href={value?.href} target={target} rel={target && 'noopener'}>{children}</a>
},
highlight: ({children}) => <span className="bg-yellow-200">{children}</span>
}
}Custom types (block-level content):
const components = {
types: {
image: ({value}) => (
<img
src={value.url}
alt={value.alt || ' '}
loading="lazy"
/>
),
callout: ({value}) => (
<div className="bg-blue-100 p-4 rounded">
{value.text}
</div>
)
}
}Important Migration Note
If you're coming from the old @sanity/block-content-to-react, the main change is that node is now value in your component props. This trips people up constantly!
Complete Example
const myPortableTextComponents = {
types: {
image: ({value}) => <img src={value.imageUrl} />,
callToAction: ({value}) => <button>{value.text}</button>
},
marks: {
link: ({children, value}) => <a href={value.href}>{children}</a>,
strong: ({children}) => <strong className="font-bold">{children}</strong>
},
block: {
h1: ({children}) => <h1 className="text-5xl">{children}</h1>,
blockquote: ({children}) => <blockquote className="border-l-4">{children}</blockquote>
},
list: {
bullet: ({children}) => <ul className="list-disc ml-4">{children}</ul>,
number: ({children}) => <ol className="list-decimal ml-4">{children}</ol>
}
}Check out this comprehensive guide on customizing Portable Text for more detailed examples, including how to match your serializers to your schema definitions.
The key insight: each component receives either children (for wrappers like marks and blocks) or value (for custom types where you need the actual data). Once that clicks, everything else falls into place!
Show original thread2 replies
Sanity – Build the way you think, not the way your CMS thinks
Sanity is the developer-first content operating system that gives you complete control. Schema-as-code, GROQ queries, and real-time APIs mean no more workarounds or waiting for deployments. Free to start, scale as you grow.