--- title: "@prismicio/react - v3" tags: ["latest"] category: "api-references" audience: developers lastUpdated: "2025-12-11T00:44:40.000Z" --- # Overview `@prismicio/react` is the official Prismic package for creating [React](https://react.dev/)-based websites. With this package, you can: * Display Prismic [images](https://prismic.io/docs/fields/image.md), [links](https://prismic.io/docs/fields/link.md), and [rich text](https://prismic.io/docs/fields/rich-text.md) using components. * Display [slice zones](https://prismic.io/docs/slice.md) with custom components. This page documents all APIs provided by `@prismicio/react`. > See the [Next.js guide](https://prismic.io/docs/nextjs.md) to learn how to build websites using this package. > **Important** > > We only guarantee support with Next.js websites. # Install `@prismicio/react` is installed when [bootstrapping](https://prismic.io/docs/nextjs.md#set-up-a-nextjs-website) a Next.js project with `@slicemachine/init`. ```sh npx @slicemachine/init@latest ``` It can also be manually installed in any React project: ```sh npm install --save @prismicio/react @prismicio/client ``` [`@prismicio/client`](https://prismic.io/docs/technical-reference/prismicio-client.md) is a peer dependency and must be installed. # API All components can be imported as a named import. The following example imports [`PrismicImage`](#prismicimage): ```ts import { PrismicImage } from "@prismicio/react"; ``` ## `` Displays an optimized image from an [image field](https://prismic.io/docs/fields/image.md). ```tsx ``` > See examples and tips on the [image field](https://prismic.io/docs/fields/image.md#display-images) page. | Prop | Type | Description | Default | | ------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | | field | ImageField | An image field to display. | None | | imgixParams (optional) | object | An object of [imgix URL parameters](https://docs.imgix.com/apis/rendering). See an [example](https://prismic.io/docs/fields/image.md#transform-images-through-the-api). | None | | alt (optional) | "" | Declare an image as decorative. | None | | fallbackAlt (optional) | "" | Declare an image as decorative if the image field does not have alt text. | None | | widths (optional) | number\[] \| "thumbnails" \| "defaults" | Widths used to build a `srcset` value for the image field.- `"thumbnails"` uses the image field's thumbnails. - `"defaults"` uses `[640, 750, 828, 1080, 1200, 1920, 2048, 3840]`.Only one of `widths` or `pixelDensities` can be used. | `"defaults"` | | pixelDensities (optional) | number\[] \| "defaults" | Pixel densities used to build a `srcset` value for the image field.- `"defaults"` uses `[1, 2, 3]`.Only one of `widths` or `pixelDensities` can be used. | None | | fallback (optional) | ReactNode | Rendered if the image is empty. | None | ## `` Displays a link from a [link field](https://prismic.io/docs/field.md#link) or Prismic document. ```tsx ``` > See examples and tips on the [link field](https://prismic.io/docs/fields/link.md#display-links) page. | Prop | Type | Description | Default | | ---------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | field | LinkField | A link field to link. Only one of `field`, `document`, or `href` can be used. | None | | document | PrismicDocument | A Prismic document to link. Only one of `field`, `document`, or `href` can be used. | None | | href | string | A URL to link. Only one of `field`, `document`, or `href` can be used. | None | | rel (optional) | undefined \| string \| ((metadata) => string \| undefined) | A `ref` attribute. A function can be passed to determine the value based on the link. Use `undefined` to remove the `rel` attribute. | `"noreferrer"` if the link is external. | | linkResolver (optional) | (field: ContentRelationshipField) => string \| null \| undefined | A [link resolver](https://prismic.io/docs/route-resolver.md#link-resolver) function used to determine a URL from the `field` or `document` prop. If it returns a value, it takes priority over a [route resolver](https://prismic.io/docs/route-resolver.md). | None | | internalComponent (optional) | ComponentType | The component used to render internal links. | `` | | externalComponent (optional) | ComponentType | The component used to render external links. | `` | ## `` Displays plain text from a [rich text field](https://prismic.io/docs/rich-text.md). ```tsx ``` | Prop | Type | Description | Default | | -------------------- | ------------- | ----------------------------------------- | ------- | | field | RichTextField | A rich text field to render. | None | | fallback (optional) | string | Rendered if the rich text field is empty. | None | | separator (optional) | string | Separator used between text blocks. | `" "` | ## `` Displays formatted text from a [rich text field](https://prismic.io/docs/rich-text.md). ```tsx ``` > See examples and tips on the [rich text field](https://prismic.io/docs/fields/rich-text.md#display-rich-text) page. | Prop | Type | Description | Default | | -------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | field | RichTextField | A rich text field to render. | None | | fallback (optional) | ReactNode | Rendered if the rich text field is empty. | None | | components (optional) | object | A map of rich text block types to React components. The available heading types are `heading1` to `heading6`. The available block types are `paragraph`, `preformatted`, `list`, `oList`, `listItem`, `oListItem`, `image`, and `embed`. The available inline types are `strong`, `em`, `hyperlink`, `label`, and `span`. See an [example](https://prismic.io/docs/fields/rich-text.md#use-custom-ui-components). | Standard HTML elements (e.g. `heading1` becomes a `

`). | | linkResolver (optional) | (field: ContentRelationshipField) => string \| null \| undefined | A [link resolver](https://prismic.io/docs/route-resolver.md#link-resolver) function used to determine a URL from the `field` or `document` prop. If it returns a value, it takes priority over a [route resolver](https://prismic.io/docs/route-resolver.md). | None | | internalLinkComponent (optional) | ComponentType | The component used to render internal links. | `` | | internalLinkComponent (optional) | ComponentType | The component used to render external links. | `` | ## `` Displays a formatted table from a [table field](https://prismic.io/docs/fields/table.md). ```tsx ``` > See examples and tips on the [table field](https://prismic.io/docs/fields/table.md#display-tables) page. | Prop | Type | Description | Default | | --------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | field | TableField | A table field to render. | None | | fallback (optional) | ReactNode | Rendered if the table field is empty. | None | | components (optional) | object | A map of table elements and rich text block types to React components. The available table elements are `table`, `thead`, `tbody`, `tr`, `th`, and `td`. The available rich text block types are `paragraph`, `em`, `strong`, and `hyperlink`. See an [example](https://prismic.io/docs/fields/table.md#use-custom-ui-components). | Standard HTML elements (e.g. `table` becomes a ``). | ## `` Renders [slices](https://prismic.io/docs/slice.md) from a slice zone. ```tsx (
), }} /> ``` > See examples and tips on the [slices](https://prismic.io/docs/slices.md#display-slices) page. | Prop | Type | Description | Default | | --------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------ | ------- | | slices | SliceZone | A slice zone to render. | None | | components | Record\> (see definition below) | A map of slice types to React components. | None | | defaultComponent (optional) | ComponentType | Rendered if a slice does not have a component mapping. | None | | context (optional) | any | Arbitrary data made available to all slice components. | None | **SliceComponentProps definition:** | Property | Type | Description | Default | | -------- | -------- | -------------------------------------------------- | ------- | | slice | Slice | The slice object being displayed. | None | | slices | Slice\[] | All slices in the slice zone. | None | | index | number | The index of the slice in the slice zone. | None | | context | unknown | The data passed to ``'s `context` prop. | None | ## `` Adds the [Prismic toolbar](https://prismic.io/docs/preview.md#the-toolbar). ```tsx ``` | Prop | Type | Description | Default | | -------------- | ------ | ----------------------------------- | ------- | | repositoryName | string | The name of the Prismic repository. | None | # Upgrade from v2 Follow these steps to upgrade an existing project to `@prismicio/react` v3. > Most Next.js websites will not require code changes. 1. **Install `@prismicio/react` v3** ```sh npm install @prismicio/react@^3 ``` 2. **Create a custom ``** > **Important** > > This step is only necessary when using ``'s `richTextComponents` or `linkResolver` props. Create a custom `` component with your default props. Use the custom component in place of `@prismicio/react`'s version. ```tsx filename=src/components/PrismicRichText.tsx import { PrismicRichText as BasePrismicRichText, PrismicRichTextProps, JSXMapSerializer, } from "@prismicio/react"; const defaultComponents: JSXMapSerializer = { heading1: ({ children }) => (

{children}

), }; export function PrismicRichText({ components, ...props }: PrismicRichTextProps) { return ( ); } ``` 3. **Create a custom ``** > **Important** > > This step is only necessary when using ``'s `internalLinkComponent`, `externalLinkComponent` or `linkResolver` props. Create a custom `` component with your default props. Use the custom component in place of `@prismicio/react`'s version. ```tsx filename=src/components/PrismicLink.tsx import { PrismicLink as BasePrismicLink, PrismicLinkProps, LinkProps, } from "@prismicio/react"; function InternalLink(props: LinkProps) { return ; } export function PrismicLink(props: PrismicLinkProps) { return ; } ``` 4. **Replace `usePrismicClient()`** Use a reference to a client instead. ```tsx import { client } from "../prismicio"; // [!code ++] function Example() { // Use the imported `client` instead. // [!code --] const client = usePrismicClient(); // [!code --] return
An example component
; } ``` We recommend exporting a client from a root-level file named `prismicio.ts`. ```tsx filename=prismicio.ts import { createClient } from "@prismicio/client"; export const client = createClient("example-prismic-repo"); ``` 5. **Replace `usePrismicPreviewResolver()`** Use [`client.resolvePreviewURL()`](https://prismic.io/docs/technical-reference/prismicio-client/v7.md#clientresolvepreviewurl) and your router's redirect function instead. ```tsx import { redirect } from "react-router"; import { useEffect } from "react"; // [!code ++] import { client } from "../prismicio"; // [!code ++] function PreviewPage() { usePrismicPreviewResolver({ navigate: redirect }); // [!code --] // prettier-ignore useEffect(() => { // [!code ++] client // [!code ++] .resolvePreviewURL({ defaultURL: "/" }) // [!code ++] .then((url) => redirect(url)); // [!code ++] }, []); // [!code ++] return
Loading...
; } ``` 6. **Replace all query hooks** Use a query library with a Prismic client, such as [TanStack Query](https://tanstack.com/query). ```tsx import { usePrismicDocumentByUID } from "@prismicio/react"; // [!code --] import { useQuery } from "@tanstack/react-query"; // [!code ++] import { client } from "../prismicio"; // [!code ++] function Home() { const [page] = usePrismicDocumentByUID("page", "home"); // [!code --] // prettier-ignore const { data } = useQuery({ // [!code ++] queryKey: ["home"], // [!code ++] queryFn: () => client.getByUID("page", "home"), // [!code ++] }); // [!code ++] return

{data?.data.title}

; } ``` > See [TanStack Query's Quick Start](https://tanstack.com/query/latest/docs/framework/react/quick-start) for details on `useQuery()`. 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()` | 7. **Remove ``** `` is no longer included. ```tsx import { PrismicProvider } from "@prismicio/react"; // [!code --] function App({ children }) { return ( // prettier-ignore // [!code --] {children} // [!code --] ); } ``` [app-router]: https://nextjs.org/docs/app [pages-router]: https://nextjs.org/docs/pages [next-image]: https://nextjs.org/docs/app/api-reference/components/image [next-link]: https://nextjs.org/docs/app/api-reference/components/link