HTML Serializer

On this article you'll learn what an HTML Serializer is, and when you can use it in your project.


The HTML Serializer is a function that helps you customize the HTML output of a Rich Text Field. The Prismic API returns Rich Texts in a structured JSON format. You need to parse this JSON to convert it to HTML (or another markup language). The rendering method will depend on your technology stack.

Our open-source development kits (prismic-dom for JavaScript, prismic-reactjs for React, and @prismicio/vue for and Vue, for example) provide default HTML Serializers. You can override the behavior of the default serializer with your own custom serializer.

How it works

The HTML Serializer receives the Rich Text JSON, evaluates it through a conditional statement, and outputs a markup template.

Here's a very simple example:

Copy
if (element.type === "emphasis") 
  return `<em>${content}</em>`

This code says, "if the type of the element is 'emphasis,' return the text inside em tags."

The HTML Serializer determines how to interpret the content of the Rich Text field in your code.

When to use it

Sometimes the default HTML Serializer doesn't cover your use case. Maybe you want to add a very precise set of class names to certain elements, or to add a unique HTML tag based on the label. That's when the HTML Serializer comes in handy.

Accessible arguments

In the JavaScript-based development kits, the HTML Serializer receives the following arguments:

type

string

The type of the element. Example: "span", "heading2", "paragraph", "image".

element

object

A description of the entire element. For inline elements, this includes the start index, end index, type, and — if the element is a custom label — the name of the label. Example:

{
"start": 0,
"end": 6,
"type": "label",
"data": { "label": "codespan" }
}

For block-level elements (eg: paragraph, headings, pre), this includes the type, the text content, and an array containing all of the inline elements. Example:

{
type: 'paragraph',
text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.',
spans: [
{
start: 63,
end: 71,
type: 'label',
data: { label: 'codespan' }
},
]
}

content

string

The content of the element. Example:

"Lorem ipsum"

children

array of strings

An array of all child elements, which have already been serialized. Example:

[
"Massa sapien faucibus ",
"<strong>cras tincidunt lobortis</strong>",
". Pharetra pharetra massa ",
"<span class=\"codespan\">ultricies</span>",
" morbi tincidunt augue interdum."
]

Example custom HTML Serializer

Here is an example use case of an HTML Serializer. It will detect if the element has a label, add a custom class name of codespan, and wrap it in a <code/> tag.

If the function doesn't match any case, it returns null and defaults to the built-in HTML Serializer.

  • JavaScript
  • React
Copy
var HtmlSerializer = function (type, element, content, children) {
  if (element.data?.label === 'codespan') {
    return `<code class="codespan">${children.join('')}<code/>`
  }
  return null
}
Copy
import React from 'react'

const propsWithUniqueKey = function (props, key) {
  return Object.assign(props || {}, { key })
}

const HtmlSerializer = (type, element, content, children, key) => {
  const props = { className: 'codespan' }
  if (element.data?.label === 'codespan') {

    return React.createElement('code', propsWithUniqueKey(props, key), children)
  }
  return null
}

export default HtmlSerializer

How to use it

To learn how to use your HTML Serializer function, see the documentation for your chosen framework.

Here are a few examples of how to use it with popular technologies:

  • JavaScript
  • React
Copy
const PrismicDOM = require('prismic-dom');

PrismicDOM.RichText.asHtml(document.data.example_rich_text, htmlSerializer)
Copy
import { RichText } from 'prismic-reactjs';

<RichText render={document.data.example_rich_text} htmlSerializer={htmlSerializer} />

Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Get in touch with us on our Community Forum.