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

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 install @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.

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()`

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

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()`

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

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.

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()`

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.

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.

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

`asTree()`

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.

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

This outputs the following tree:

{
  "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": []
        }
      ]
    }
  ]
}