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 (@prismicio/helpers for JavaScript, @prismicio/react 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 brief example:

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:



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



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' }



The content of the element. Example:

"Lorem ipsum"


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."

Note that @prismicio/helpers v2 joins this array as a string by default, so the children parameter will look like this:

"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
const HtmlSerializer = function (type, element, content, children) {
  if ( === 'codespan') {
    return `<code class="codespan">${children.join('')}<code/>`

  return null
import * as React from 'react'

const HtmlSerializer = (type, element, content, children, key) => {
  if ( === 'codespan') {
    return (
      <code key={key} className="codespan">

  return null

export default HtmlSerializer

How to use a custom HTML Serializer

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:

  • Vanilla JavaScript
  • React
Vanilla JavaScript
import * as prismicH from '@prismicio/helpers'

const contentText = prismicH.asHTML(, null, htmlSerializer);
import { PrismicRichText } from '@prismicio/react'


// Or if you need a simpler approach

    heading1: ({ children }) => <Heading>{children}</Heading>,
    paragraph: ({ children }) => <p className="paragraph">{children}</p>,

Example complete HTML Serializer

To see how @prismicio/helpers serializes every available element by default, see the code for the default HTML Serializer on GitHub.

Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.