@prismicio/react - v3

Overview

@prismicio/react is the official Prismic package for creating React-based websites.

With this package, you can:

• Display Prismic images, links, and rich text.
• Display slice zones with custom components.

Install

@prismicio/react is automatically installed when bootstrapping a Next.js project with @slicemachine/init.

npx @slicemachine/init@latest

It can also be manually installed in any React project:

npm install --save @prismicio/react @prismicio/client

@prismicio/client is a peer dependency and must be installed.

API

<PrismicImage>

Displays an optimized image from an image field.

<PrismicImage field={slice.primary.image} />

<PrismicLink>

Displays a link from a link field or Prismic document.

<PrismicLink field={slice.primary.link} />

<PrismicText>

Displays plain text from a rich text field.

<PrismicText field={slice.primary.text} />

<PrismicRichText>

Displays formatted text from a rich text field.

<PrismicRichText field={slice.primary.text} />

<SliceZone>

Renders slices from a slice zone.

<SliceZone
  slices={doc.data.slices}
  components={{
    text: ({ slice }) => (
      <section>
        <PrismicRichText field={slice.primary.text} />
      </section>
    ),
  }}
/>

<PrismicToolbar>

Adds the Prismic toolbar.

<PrismicToolbar repositoryName="example-prismic-repo" />

Upgrade from v2

Follow these steps to upgrade an existing project to @prismicio/react v3.

• Install @prismicio/react v3

  npm install @prismicio/react@^3

• Create a custom <PrismicRichText>

  Create a custom <PrismicRichText> component with your default props. Use the custom component in place of @prismicio/react’s version.

  src/components/PrismicRichText.tsx

  Copy

  import {
    PrismicRichText as BasePrismicRichText,
    PrismicRichTextProps,
    JSXMapSerializer,
  } from "@prismicio/react";
  
  const defaultComponents: JSXMapSerializer = {
    heading1: ({ children }) => (
      <h1 className="font-bold text-3xl">{children}</h1>
    ),
  };
  
  export function PrismicRichText({
    components,
    ...props
  }: PrismicRichTextProps) {
    return (
      <BasePrismicRichText
        components={{ ...defaultComponents, ...components }}
        {...props}
      />
    );
  }

• Create a custom <PrismicLink>

  Create a custom <PrismicLink> component with your default props. Use the custom component in place of @prismicio/react’s version.

  src/components/PrismicLink.tsx

  Copy

  import {
    PrismicLink as BasePrismicLink,
    PrismicLinkProps,
    LinkProps,
  } from "@prismicio/react";
  
  function InternalLink(props: LinkProps) {
    return <a className="internal" {...props} />;
  }
  
  export function PrismicLink(props: PrismicLinkProps) {
    return <BasePrismicLink internalComponent={InternalLink} {...props} />;
  }

• Replace usePrismicClient()

  Use a reference to a client instead.

  import { client } from "../prismicio"; 
  
  function Example() {
    // Use the imported `client` instead. //
    const client = usePrismicClient(); 
  
    return <div>An example component</div>;
  }

  We recommend exporting a client from a root-level file named prismicio.ts.

  prismicio.ts

  Copy

  import { createClient } from "@prismicio/client";
  
  export const client = createClient("example-prismic-repo");

• Replace usePrismicPreviewResolver()

  Use client.resolvePreviewURL() and your router’s redirect function instead.

  import { redirect } from "react-router";
  import { useEffect } from "react"; 
  import { client } from "../prismicio"; 
  
  function PreviewPage() {
    usePrismicPreviewResolver({ navigate: redirect }); 
    useEffect(() => { 
      client
        .resolvePreviewURL({ defaultURL: "/" }) 
        .then((url) => redirect(url)); 
    }, []); 
  
    return <div>Loading...</div>;
  }

• Replace all query hooks

  Use a query library with a Prismic client, such as TanStack Query.

  import { usePrismicDocumentByUID } from "@prismicio/react"; 
  import { useQuery } from "@tanstack/react-query"; 
  import { client } from "../prismicio"; 
  
  function Home() {
    const [page] = usePrismicDocumentByUID("page", "home"); 
    const { data } = useQuery({ 
      queryKey: ["home"], 
      queryFn: () => client.getByUID("page", "home"), 
    }); 
  
    return <h1>{data?.data.title}</h1>;
  }

  Refer to the following table for each hook’s replacement client method.

  Hook	Query method
  usePrismicDocuments()	client.get()
  useFirstPrismicDocument()	client.getFirst()
  useAllPrismicDocumentsDangerously()	client.dangerouslyGetAll()
  usePrismicDocumentByID()	client.getByID()
  usePrismicDocumentsByIDs()	client.getByIDs()
  useAllPrismicDocumentsByIDs()	client.getAllByIDs()
  usePrismicDocumentByUID()	client.getByUID()
  usePrismicDocumentsByUIDs()	client.getByUIDs()
  useAllPrismicDocumentsByUIDs()	client.getAllByUIDs()
  useSinglePrismicDocument()	client.getSingle()
  usePrismicDocumentsByType()	client.getByType()
  useAllPrismicDocumentsByType()	client.getAllByType()
  usePrismicDocumentsByTag()	client.getByTag()
  useAllPrismicDocumentsByTag()	client.getAllByTag()
  usePrismicDocumentsBySomeTags()	client.getBySomeTags()
  useAllPrismicDocumentsBySomeTags()	client.getAllBySomeTags()
  usePrismicDocumentsByEveryTag()	client.getByEveryTag()
  useAllPrismicDocumentsByEveryTag()	client.getAllByEveryTag()

• Remove <PrismicProvider>

  <PrismicProvider> is no longer included.

  import { PrismicProvider } from "@prismicio/react"; 
  
  function App({ children }) {
    return (
      <PrismicProvider client={client}>
        {children}
      </PrismicProvider>
    );
  }