---
title: "@prismicio/react - v2 Migration Guide"
description: "This is a guide for upgrading a project using prismic-reactjs v1 to @prismicio/react v2."
meta_title: "@prismicio/react v2 Migration Guide"
audience: developers
lastUpdated: "2025-11-06T01:07:50.000Z"
---

# Overview

This is a guide for upgrading a project using `prismic-reactjs` v1 to `@prismicio/react` v2.

In addition to a new package name, `@prismicio/react` v2 provides a more focused, more React-like set of components and hooks that facilitate rendering Prismic content.

The following instructions walk you through upgrading to the updated package.

## Benefits of upgrading

* Declaratively render slice zones
* Easier Rich Text field rendering customization
* Handle internal and external links with a smart link component
* Fetch Prismic content using hooks
* First-class TypeScript support

# Update packages in package.json

1. Update your `package.json` to use the latest version of `@prismicio/react`.

```json
{
  "dependencies": {
    "@prismicio/react": "^2.0.0"
  }
}
```

2. Remove `prismic-reactjs` from your `package.json`. `@prismicio/react` v2 replaces the previous `prismic-reactjs` package.

```diff
  {
    "dependencies": {
-     "prismic-reactjs": "^2.2.6"
    }
  }
```

3. Update your installed packages with `npm`.

```bash
npm install
```

# Handling breaking changes

The following changes are required when upgrading to `@prismicio/react` v2.

## Replace `<RichText>` with `<PrismicRichText>`

The `<RichText>` component has been replaced by a new component called `<PrismicRichText>`. The new component renders Rich Text and Title fields like the previous component, but with different props.

Rename the `render` prop to `field`. The `field` prop accepts a Rich Text or Title field.

```diff
  <PrismicRichText
-   render={document.data.myRichTextField}
+   field={document.data.myRichTextField}
  />
```

Rename the `htmlSerializer` prop to `components`. The `components` prop accepts an HTML Serializer, like the previous component, but also accepts a simpler object form instead (see [Convert HTML Serializer function to an object](https://prismic.io/docs/technologies/prismic-react-v2-migration-guide#convert-html-serializer-function-to-an-object) in the New Features section below).

```diff
  <PrismicRichText
    field={document.data.description}
-   htmlSerializer={
+   components={
      (type, node, text, children, key) => {
        // Your serializer
      }
    }
  />
```

Remove the `serializeHyperlink` prop. By default, `<PrismicRichText>` will render links using `<PrismicLink>`. The behavior of `<PrismicLink>` can be customized with the following props:

* `internalLinkComponent`: The component rendered for internal links.
* `externalLinkComponent`: The component rendered for external links.

```diff
  <PrismicRichText
    field={document.data.description}
-   serializeHyperlink={customLink}
+   internalLinkComponent={({ href, ...props }) => (
+     <Link to={href} {...props} />
+   )}
  />
```

It can also be customized in a centralized location in `<PrismicProvider>` (see [Configure components in `<PrismicProvider>`](https://prismic.io/docs/technologies/prismic-react-v2-migration-guide#configure-components-in-prismicprovider) in the New Features section below).

To completely replace the component used for links, use the `components` prop to return a React component for the `hyperlink` block type.

```tsx
<PrismicRichText
  field={document.data.description}
  components={{
    hyperlink: ({ children, node }) => {
      /* Your custom link component */
    },
  }}
/>
```

## Replace `RichText.asText()` with `<PrismicText>` or `asText()`

The `RichText.asText()` function has been replaced by a React component called `<PrismicText>`. If your app uses `RichText.asText()` within a component's return value, you can replace it with the new component.

```diff
- import { RichText } from 'prismic-reactjs'
+ import { PrismicText } from '@prismicio/react'

  <p>
-   {RichText.asText(document.data.description)}
+   <PrismicText field={document.data.description} />
  </p>
```

If your app uses `RichText.asText()` to convert a Rich Text or Title field to a string outside a component's return value, you can replace it with `@prismicio/helpers`'s `asText()` function. Note that you will need to install `@prismicio/helpers` if you don't already have it installed.

```diff
- import { RichText } from 'prismic-reactjs'
+ import * as prismicH from '@prismicio/helpers'

  const App = () => {
-   const description = RichText.asText(document.data.description)
+   const description = prismicH.asText(document.data.description)

    // The rest of your component...
  }
```

## Replace `Link.url()` with `<PrismicLink>` or `asLink()`

The `Link.url()` function has been replaced by a React component called `<PrismicLink>`. If you app uses `Link.url()` within a component's return value, you can replace it with the new component.

```diff
- import { Link } from 'prismic-reactjs'
+ import { PrismicLink } from '@prismicio/react'

- <a href={Link.url(document.data.link)}>Click me</a>
+ <PrismicLink field={document.data.link}>Click me</PrismicLink>
```

If your app uses `Link.url()` to convert a Link field to a URL string outside a component's return value, you can replace it with `@prismicio/helpers`'s `asLink()` function. Note that you will need to install `@prismicio/helpers` if you don't already have it installed.

```diff
- import { Link } from 'prismic-reactjs'
+ import * as prismicH from '@prismicio/helpers'

  const App = () => {
-   const url = Link.url(document.data.link)
+   const url = prismicH.asLink(document.data.link)

    // The rest of your component...
  }
```

## Replace `Date()` with `asDate()`

The `Date()` function has been removed from the React library. Replace it with `@prismicio/helpers`'s `asDate()` function. It accepts the same arguments and returns the same JavaScript Date object as the previous `Date()` function.

```diff
- import { Date } from 'prismic-reactjs'
+ import * as prismicH from '@prismicio/helpers'

- Date(document.data.date)
+ prismicH.asDate(document.data.date)
```

## Replace `Elements` with `Element`

If your app uses an HTML Serializer, replace the `Elements` import with the `Element` import (note that the "s" has been removed). The renamed object contains the same values but requires a different import name.

```diff
- import { Elements } from 'prismic-reactjs'
+ import { Element } from '@prismicio/react'
```

# New features

While migrating to `@prismicio/react` v2, you may also want to make use of new features included in the upgraded library.

The following steps are optional but recommended.

## Configure components in `<PrismicProvider>`

Certain components in `@prismicio/react` can be customized in a central `<PrismicProvider>` component at the top of your app's component tree. This lets you define how components are rendered throughout your whole app.

The following components and hooks can be configured in the provider:

* `<PrismicLink>`: Define your app's Link Resolver and internal and external link components.
* `<PrismicRichText>`: Define your app's standard collection of components for Rich Text rendering.
* All data-fetching hooks: Define the Prismic API client used to fetch content from your Prismic repository.

See the [`@prismicio/react` Technical Reference](https://prismic.io/docs/technical-reference/prismicio-react.md) for more details.

## Use `<PrismicLink>` to render links

`<PrismicLink>` provides a way to render all links in your app. It supports Prismic Link fields and standard URLs. It can automatically render different components for internal and external links (helpful when you have a client-site router that needs a special `<Link>` component).

```tsx
<PrismicLink field={document.data.myLinkField}>Click me</PrismicLink>
```

See the [@prismicio/react Technical Reference](https://prismic.io/docs/prismic-react-v2-migration-guide.md) for more details on what `<PrismicLink>` can do.

## Convert HTML Serializer function to an object

`<PrismicRichText>` supports the function form of an HTML Serializer through the `components` prop. It now also supports a simpler, more condensed object form. It serves the same purpose as the function form but with less code.

```tsx
<PrismicRichText
  field={document.data.myRichTextField}
  components={{
    heading1: ({ children }) => <Heading>{children}</Heading>,
    paragraph: ({ children }) => <p className="paragraph">{children}</p>,
  }}
/>
```

See the [@prismicio/react Technical Reference](https://prismic.io/docs/prismic-react-v2-migration-guide.md) for more details on writing an object HTML Serializer.

## Declaratively render slice zones

Apps typically contain a `.map()` function with a `switch` statement to render slice zones. To simplify the process of rendering a slice zone, a `<SliceZone>` component has been added to the library. It accepts a list of slices and a component for each slice type and renders it accordingly.

```tsx
<SliceZone
  slices={document.data.body}
  components={{
    text: TextSlice,
    images: ImagesSlice,
  }}
/>
```

See the [@prismicio/react Technical Reference](https://prismic.io/docs/prismic-react-v2-migration-guide.md) for more details on rendering slice zones.

## Add the Prismic Toolbar with `<PrismicToolbar>`

The Prismic Toolbar is essential to support content previews in your app. This is typically done by adding a `<script>` element in the `<head>` of your app. To simplify this setup, a `<PrismicToolbar>` component has been added to the library. It just needs your Prismic repository name to render the appropriate `<script>` element.

```tsx
<PrismicToolbar repositoryName="repo-name" />
```

## TypeScript

`@prismicio/react` is written in TypeScript with TypeScript users in mind. All components and hooks exported by the updated package include types so you will benefit without any changes to your code.

The package exports a collection of types that may be useful throughout your projects.

See the `@prismicio/react` TypeScript documentation for a list of the available types.