NEW

Prismic offers an ideal solution to feature your e-commerce products in your promotional landing pages or inspirational content. View more

New React Library Beta

Written by Angelo Ashmore in announcement on November 05, 2021

Prismic loves React

The Prismic team has been working on redefining how developers work with Prismic in their projects. We want to make the process of fetching and displaying content from Prismic as easy and intuitive as possible.

Today, we're excited to share a beta version of this new experience for React developers, including those using Next.js and Gatsby.

It represents how we see developers working with Prismic content within their projects. Although this beta is specifically for React developers, you can expect to see similar updates for other libraries like Vue.js and Svelte.

These key features make development easier:

  • A standard Slice Zone component: <SliceZone> makes it easy to render Slice Zones.
  • Easier Rich Text rendering: <PrismicRichText> is simple and flexible.
  • Intuitive link handling: <PrismicLink> automates complicated link rendering.
  • Deep TypeScript integration: Written for TypeScript developers by TypeScript developers.

👉 TL;DR: We have a new @prismicio/react library you can beta test today. It contains new and refreshed components and hooks that make working with Prismic in React even easier than before.

npm install @prismicio/react@beta

For a full API reference with examples on how to use the components, see the @prismicio/react technical reference.

This update includes breaking changes to the existing library, so please take a look at the API reference while trying it out. A step-by-step upgrade guide from the current version will be available for the full release.

What's new

Many changes have been introduced in the new library — too many to show in this blog post alone. Below are some of the key changes that have a big impact on developer efficiency.

A standard Slice Zone component

Slices are one of Prismic's most powerful features. It lets developers build sites with components and lets editors write with pre-designed blocks. Before today, developers needed to write their own way of rendering Slices.

@prismicio/react introduces a standard <SliceZone> component that makes this process easy.

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

Just give <SliceZone> a list of Slices from a Prismic document and a list of React components for each type of Slice. It will render each of the document's Slices with the correct component.

Easier Rich Text rendering

Rich Text fields are core to any site; they're how text is saved and displayed on any Prismic-powered website. The updated <PrismicRichText> component makes it easy to properly render Rich Text content with custom components and automatic link rendering.

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

Using the new <PrismicProvider>, you can even define all of your custom Rich Text components in one place for all your <PrismicRichText> components.

function App({ children }) {
  return (
    <PrismicProvider
      richTextComponents={{
        heading1: ({ children }) => <Heading>{children}</Heading>,
        paragraph: ({ children }) => <p className="paragraph">{children}</p>,
      }}
    >
      {children}
    </PrismicProvider>
  );
}

With that in place, Rich Text rendering throughout your site can be as simple as this:

<PrismicRichText field={document.data.myRichTextField} />

Intuitive link handling

Rendering links from Prismic documents requires a bit of work. Sometimes links point to other documents, sometimes to external websites, and sometimes are left empty in the CMS. Add in a client-side React router and things get even more complicated.

<PrismicLink> helps you by handling all of these cases for you. You just need to provide a few props depending on your use case.

<PrismicLink
  field={document.data.myLinkField}
  internalComponent={Link}
  externalComponent={(props) => <a className="external" {...props} />}
>
  Click me
</PrismicLink>

This link will automatically render <Link> if the URL is internal or <a className="external" /> if it is external. It adds the correct rel and target attributes accordingly as well. And like <PrismicRichText>'s configuration, these options can be provided in one place for all your links.

function App({ children }) {
  return (
    <PrismicProvider
      linkResolver={linkResolver}
      internalLinkComponent={Link}
      externalComponent={(props) => <a className="external" {...props} />}
    >
      {children}
    </PrismicProvider>
  );
}

With that in place, link rendering throughout your site can be as simple as this:

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

Deep TypeScript integration

Using TypeScript is like having a superpower. With the proper setup, you can develop quicker and more confidently as your code editor guides you through the process. This all relies on the libraries you use having good TypeScript support.

With this in mind, we've developed the new React library with a strong TypeScript focus. We built it upon @prismicio/types, a TypeScript types library full of accurate Prismic typings.

Even if you aren't using TypeScript in your project, your editor likely can hook into these types to provide a more helpful development experience. (I strongly recommend at least trying TypeScript if you can!)

How to try it

You can install the new React library beta with the following command:

npm install @prismicio/react@beta

For a full API reference with examples on how to use the components, see the @prismicio/react technical reference.

This update includes breaking changes to the existing library, so please take a look at the API reference while trying it out. A step-by-step upgrade guide from the current version will be available for the full release.

We expect to publish the full release sometime in December.

How to give feedback or report bugs

As always, if you have any questions or run into issues with the new library, please feel free to reach out for help with the methods below. Hearing your thoughts on the new experience is especially important and welcome during this beta period.

❓ Ask a question
Open a new topic on our community forum with your question explaining what you want to achieve. Our support team will get back to you shortly.

🐛 Report a bug
Open an issue explaining your application's setup and the bug you're encountering.

💬 Suggest an improvement
Open an issue explaining your improvement or feature so we can discuss and learn more.

🧑‍💻 Submit code changes
For small fixes, feel free to open a pull request with a description of your changes. For large changes, please first open an issue so we can discuss if and how the changes should be implemented.

We hope you like the changes we've made and are excited to hear what you think of it. It's not too late to suggest improvements, so please try it out and share your thoughts!

Profile picture

Angelo Ashmore

Developer Experience Engineer at Prismic focusing on Gatsby, React, and TypeScript, in no particular order.