---
title: "@prismicio/richtext - v2"
category: "api-references"
audience: developers
lastUpdated: "2025-11-06T01:07:50.000Z"
---

> **Caution**
>
> **This package is no longer supported**. Learn how to upgrade to its replacement in the [`@prismicio/client` v7 migration guide](https://prismic.io/docs/prismicio-client-v7-migration-guide.md#replace-prismiciorichtext-imports-with-prismicioclientrichtext).

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

> <CalloutHeading>Do you need this package?</CalloutHeading>
>
> Most users will not use this package directly. The following packages provide an easier-to-use API:
>
> * [`@prismicio/client`](https://prismic.io/docs/technical-reference/prismicio-client.md): Convert to HTML or plain text
> * [`@prismicio/react`](https://prismic.io/docs/technical-reference/prismicio-react.md): Convert to React components or plain text
> * [`@prismicio/vue`](https://prismic.io/docs/technical-reference/prismicio-vue.md): 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

```bash
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`.

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

```tsx
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

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

```tsx
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

```tsx
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.

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

```tsx
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.

```tsx
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.

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

## `asTree()`

```tsx
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.

> <CalloutHeading>Should you use this function?</CalloutHeading>
>
> 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()`.)

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

This outputs the following tree:

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