@prismicio/richtext - v2

Overview

@prismicio/richtext provides a set of functions to convert rich text or title field values into other formats, such as HTML or React components.

Do you need this package?

Most users will not use this package directly. The following packages provide an easier-to-use API:

@prismicio/client: Convert to HTML or plain text
@prismicio/react: Convert to React components or plain text
@prismicio/vue: Convert to Vue components or plain text

If you need a different output format not listed above, you should use this package.

Dependencies

This package works with the Prismic API V2. Most Prismic users are on V2 by default. You can tell if you're using V2 if your endpoint URL includes prismic.io/api/v2.

Installation

npm
Yarn

npm

Copy

npm install @prismicio/richtext

Yarn

Copy

yarn add @prismicio/richtext

Example

In this example, we will use @prismicio/richtext to convert a rich text field from its original value to Markdown.

This example assumes that you have queried the Prismic API and saved a document object in a variable named document.

Copy

import * as prismicR from '@prismicio/richtext'
import * as prismic from '@prismicio/client'

// Used to convert links into URLs.
const linkResolver = (doc) => `/${doc.uid}`

// An object mapping rich text block types to Markdown.
const markdownSerializer = prismicR.wrapMapSerializer({
  heading1: ({ children }) =>
    `# ${children.join('')}\n\n`,
  heading2: ({ children }) =>
    `## ${children.join('')}\n\n`,
  heading3: ({ children }) =>
    `### ${children.join('')}\n\n`,
  heading4: ({ children }) =>
    `#### ${children.join('')}\n\n`,
  heading5: ({ children }) =>
    `##### ${children.join('')}\n\n`,
  heading6: ({ children }) =>
    `###### ${children.join('')}\n\n`,
  paragraph: ({ children }) =>
    `${children.join('')}\n\n`,
  preformatted: ({ text }) =>
    `\`\`\`\n${text}\n\`\`\`\n\n`,
  strong: ({ children }) =>
    `**${children.join('')}**`,
  em: ({ children }) =>
    `_${children.join('')}_`,
  listItem: ({ children }) =>
    `- ${children.join('')}\n`,
  oListItem: ({ children }) =>
    `1. ${children.join('')}\n`,
  list: ({ children }) =>
    `${children.join('')}\n`,
  oList: ({ children }) =>
    `${children.join('')}\n`,
  image: ({ node }) =>
    node.linkTo
      ? `[![${node.alt}](${node.url})](${node.linkTo.url})\n\n`
      : `![${node.alt}](${node.url})\n\n`,
  embed: ({ node }) =>
    `${node.oembed.html}\n\n`,
  hyperlink: ({ node, children }) =>
    `[${children.join('')}](${prismic.asLink(node.data, linkResolver)})`,
  label: ({ children }) =>
    children.join(''),
  span: ({ text }) =>
    text.replace('\n', '<br/>'),
})

// Convert a rich text or title field into Markdown using the Markdown
// serializer from above.
const markdown = prismicR
  .serialize(document.data.example_rich_text, markdownSerializer)
  .join('')

Usage

This section assumes you have required @prismicio/richtext in your project and stored it in a variable called prismicR and that you have queried a document from the Prismic API and stored it in a variable called document.

Here are all of the functions provided by @prismicio/richtext:

`serialize()`

Copy

serialize(richTextField, serializer)

This function converts a rich text or title field into a different format determined by the serializer parameter. The function returns an array of converted values.

The serializer parameter should be a function that accepts the following parameters for a particular rich text block and returns its converted value.

type: The type of the block (e.g. heading1, paragraph)
node: The block and its embedded data
text: The plain text contained in the block
children: Converted children of the block
key: A unique value used to identify the block within the rich text field

Copy

const serializer = (type, node, text, children, key) => {
  switch (type) {
    case 'paragraph': {
      return { element: 'p', text }
    }
  }
}

prismicR.serialize(document.data.example_rich_text, serializer)
// [{ element: 'p', text: 'This is a paragraph' }]

Note that any value can be returned by the serializer. An object is used here just as an example.

Serializer functions can be more easily written using the wrapMapSerializer helper.

`wrapMapSerializer()`

Copy

wrapMapSerializer(mapSerializer)

This function provides an easier way to write rich text serializers using an object syntax. This function converts the object serializer into a function serializer, which is expected by the serialize function described above.

The mapSerializer parameter should be an object mapping a rich text block type to a function returning a block's converted value.

Each function can destructure the following parameters:

type: The type of the block (e.g. heading1, paragraph)
node: The block and its embedded data
text: The plain text contained in the block
children: Converted children of the block
key: A unique value used to identify the block within the rich text field

Copy

const serializer = prismicR.wrapMapSerializer({
  paragraph: ({ text }) => ({ element: 'p', text }),
})

prismicR.serialize(document.data.example_rich_text, serializer)
// [{ element: 'p', text: 'This is a paragraph' }]

Note that any value can be returned by a serializer function. An object is used here just as an example.

`composeSerializers()`

This function combines two or more serializers into one. If you have a serializer that handles headings, for example, and another that handles everything else, they can be combined using this function.

If a serializer returns null or undefined, the next serializer is attempted. Serializers are evaluated left to right. If the first serializer returns null for a heading1 block, for example, the next serializer will be attempted.

If all serializers return null or undefined for a block, the block is not included in the serialized return value.

Copy

const serializer1 = prismicR.wrapMapSerializer({
  heading1: ({ text }) => ({ element: 'h1', text }),
})

const serializer2 = prismicR.wrapMapSerializer({
  paragraph: ({ text }) => ({ element: 'p', text }),
})

const serializer = prismicR.composeSerializers(serializer1, serializer2)

prismicR.serialize(document.data.example_rich_text, serializer)

`asText()`

Copy

asText(richTextField)
asText(richTextField, separator)

This function converts a rich text or title field into plain text. All formatting, such as headings and text styling, is removed.

Copy

prismicR.asText(document.data.example_rich_text)
// This is a paragraph This is another paragraph

By default, blocks are joined by a space (" "). This behavior can be overridden by passing a string to the separator parameter.

Copy

prismicR.asText(document.data.example_rich_text, '\n')
// This is a paragraph\nThis is another paragraph

`asTree()`

Copy

asTree(richTextField)

This function converts a rich text or title field into a nested tree structure. It will calculate and rearrange nested children in a rich text field block.

Should you use this function?

Most users will not need to use asTree(). It is only useful if you need custom serialization behavior that cannot be accomplished with serialize(). (asTree() is used internally in serialize().)

Copy

const tree = prismicR.asTree([
  {
    type: 'paragraph',
    text: 'This text contains bold styling.',
    spans: [
      {
        start: 19,
        end: 23,
        type: 'strong',
      },
    ],
  },
])

This outputs the following tree:

Copy

{
  "key": "6",
  "children": [
    {
      "key": "5",
      "type": "paragraph",
      "text": "This text contains bold styling.",
      "node": {
        "type": "paragraph",
        "text": "This text contains bold styling.",
        "spans": [{ "start": 19, "end": 23, "type": "strong" }]
      },
      "children": [
        {
          "key": "1",
          "type": "span",
          "text": "This text contains ",
          "node": {
            "type": "span",
            "text": "This text contains ",
            "spans": []
          },
          "children": []
        },
        {
          "key": "3",
          "type": "strong",
          "text": undefined,
          "node": { "start": 19, "end": 23, "type": "strong" },
          "children": [
            {
              "key": "2",
              "type": "span",
              "text": "bold",
              "node": { "type": "span", "text": "bold", "spans": [] },
              "children": []
            }
          ]
        },
        {
          "key": "4",
          "type": "span",
          "text": " styling.",
          "node": { "type": "span", "text": " styling.", "spans": [] },
          "children": []
        }
      ]
    }
  ]
}

Can't find what you're looking for?

Need technical Support? Spot an error in the documentation? Get in touch with us on our Community Forum.