---
title: "@prismicio/migrate - v0"
tags: ["latest"]
category: "api-references"
audience: developers
lastUpdated: "2025-11-06T01:07:50.000Z"
---

# Overiew

`@prismicio/migrate` helps you migrate content to Prismic.

# Installation

```bash
npm install @prismicio/migrate
```

# Usage

Helpers should be imported individually from `@prismicio/migrate`.

```tsx
import { htmlAsRichText } from "@prismicio/migrate";
```

> **This package is ESM-only.**
>
> If you are using CommonJS, you can import the package using `import()`.
>
> ```
> const { htmlAsRichText } = await import('@prismicio/migrate')
> ```

`@prismicio/migrate` provides the following functions.

## `htmlAsRichText()`

```tsx
htmlAsRichText(html);
htmlAsRichText(html, config);
```

`htmlAsRichText()` converts HTML to Prismic rich text. It can be used with the [Migration API](https://prismic.io/docs/migration-api-technical-reference.md).

```tsx
const {
  result, // Prismic rich text
  warnings, // Warning messages
} = htmlAsRichText(html);
```

`htmlAsRichText()` supports common HTML elements by default, like `<h1>` and `<p>`. The defaults can be extended or overridden using the serializer option.

```tsx
import { htmlAsRichText, RichTextHTMLMapSerializer } from "@prismicio/migrate";

const serializer: RichTextHTMLMapSerializer = {
  // Converts HTML `h1` elements to rich text `heading2` nodes.
  h1: "heading2",

  // Converts `div` elements with the `paragraph` class to rich text
  // heading1 nodes.
  "div.paragraph": "paragraph",
  // Complex selectors are supported.
  "h1 + p": "heading2",

  // Output node types can be used as many times as needed.
  b: "strong",
  strong: "strong",

  // Rich text labels are declared using an object with its name.
  "code.inline": { label: "code" },

  // Functions can be used for advanced cases. They receive the HTML
  // node and context object. They should return a rich text node type
  // like the above examples or a full rich text node object.
  "foo-element": ({ node, context }) =>
    node.properties.heading ? "heading1" : "paragraph",
  "bar-element": ({ node, context }) => ({
    type: "paragraph",
    text: "",
    spans: [],
  }),
};

htmlAsRichText(html, { serializer });
// [{ type: 'heading2', text: 'html as rich text', spans: [...] }, ...]
```

If an element is mapped to `undefined`, the element will be ignored. Its children will continue to be processed.

To convert only a section of an HTML document, pass a CSS selector to the `container` option. By default, the whole document is converted.

```tsx
htmlAsRichText(html, { container: "div#post" });
```

To exclude HTML elements, pass an array of CSS selectors to the `exclude` option.

```tsx
htmlAsRichText(html, { exclude: [".hidden", "aside"] });
```

To include only a set of HTML elements and their children, pass an array of CSS selectors to the `include` option.

```tsx
htmlAsRichText(html, { include: ["p", "img"] });
```

To set the text direction of the output’s content, use the `direction` option. By default, content is marked as left-to-right.

```tsx
htmlAsRichText(html, { direction: "rtl" });
// [{ type: 'heading1', text: 'سلام دنیا', spans: [...], direction: 'rtl' }, ...]
```

Rich text fields can be restricted to a subset of rich text blocks. For example, a field may support headings and paragraphs, but not images. To ensure only supported block types are used, pass the field’s model to the `model` option.

```tsx
// Models are configured within Slice Machine and available in your file system.
const model = {
  type: "StructuredText",
  config: { multi: "heading1,paragraph,strong" },
};

htmlAsRichText(html, { model });
```

All configuration options can be used alongside each other.

```tsx
const serializer = {
  b: "strong",
};

const model = {
  type: "StructuredText",
  config: { multi: "paragraph,image,strong" },
};

// This example does the following:
// - Converts `<p>` and `<img>` elements within `div#post`.
// - Ignores `<aside>` elements and elements with the "hidden" class.
// - Converts `<b>` elements to `strong` rich text nodes.
// - Marks all text as left-to-right.
// - Ensures the output fits the provided model.
htmlAsRichText(html, {
  serializer,
  container: "div#post",
  exclude: [".hidden", "aside"],
  include: ["p", "img"],
  direction: "ltr",
  model,
});
// [{ type: 'heading1', text: 'html as rich text', spans: [...] }, ...]
```