--- title: "@prismicio/next - v2" tags: ["latest"] category: "api-references" audience: developers lastUpdated: "2026-01-15T00:40:43.000Z" --- # Overview `@prismicio/next` is the official Prismic package for creating [Next.js](https://nextjs.org/) websites. With this package, you can: * Set up Prismic [previews](https://prismic.io/docs/preview.md). * Display Prismic images using [`next/image`](https://nextjs.org/docs/app/api-reference/components/image). * Display Prismic links using [`next/link`](https://nextjs.org/docs/app/api-reference/components/link). This page documents all APIs provided by `@prismicio/next`. > See the [Next.js guide](https://prismic.io/docs/nextjs.md) to learn how to build websites using this package. > **Important** > > If your website uses the Pages Router, see [Use with the Pages Router](#use-with-the-pages-router). # Install `@prismicio/next` 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 Next.js project: ```sh npm install --save @prismicio/next @prismicio/client ``` [`@prismicio/client`](https://prismic.io/docs/technical-reference/prismicio-client.md) is a peer dependency and must be installed. # Use with the Pages Router `@prismicio/next` supports the [App Router](https://nextjs.org/docs/app) (recommended) and the [Pages Router](https://nextjs.org/docs/pages). To use `@prismicio/next` with the Pages Router, import components and helpers using the `@prismicio/next/pages` entry. ```ts // [!code word:/pages:1] import { PrismicPreview } from "@prismicio/next/pages"; ``` The `/pages` entry provides Pages Router-specific implementations. # API All components can be imported as a named import. The following example imports [`PrismicNextImage`](#prismicnextimage): ```ts import { PrismicNextImage } from "@prismicio/next"; ``` ## `` Displays an optimized image from an [image field](https://prismic.io/docs/fields/image.md) using [`next/image`](https://nextjs.org/docs/api-reference/next/image). ```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 | | fallback (optional) | ReactNode | Rendered if the image is empty. | `null` | | loader (optional) | function | Use a custom [`next/image` loader](https://nextjs.org/docs/pages/api-reference/components/image#loader). Images are served via [imgix](https://www.imgix.com) by default. | None | | ...rest (optional) | undefined | All [`next/image` props](https://nextjs.org/docs/app/api-reference/components/image#props) are supported except `src`. | None | ## `` Displays a link from a [link field](https://prismic.io/docs/fields/link.md) or Prismic document using [`next/link`](https://nextjs.org/docs/api-reference/next/link). ```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 \| function | A `ref` attribute. A function can be passed to determine the value based on the link. | None | | 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 | | ...rest (optional) | undefined | All [`next/link` props](https://nextjs.org/docs/app/api-reference/components/link#reference) are supported. | None | ## `` Adds support for [content previews](https://prismic.io/docs/preview.md) by including the Prismic toolbar and event listeners. Webpages are automatically refreshed when a new content draft is saved. ```tsx ``` | Prop | Type | Description | Default | | --------------------------- | ------ | ----------------------------------------------- | --------------------- | | repositoryName | string | The Prismic repository name. | None | | updatePreviewURL (optional) | string | The URL fetched when draft content is updated. | `"/api/preview"` | | exitPreviewURL (optional) | string | The URL fetched when exiting a preview session. | `"/api/exit-preview"` | ## `` Adds support for [live slice previews](https://prismic.io/docs/nextjs.md#live-previews-in-the-page-builder) in the Page Builder and Slice Machine. ```tsx ``` > See the [Next.js guide](https://prismic.io/docs/nextjs.md#live-previews-in-the-page-builder) to learn how to set up live previews. | Prop | Type | Description | Default | | --------------------- | --------- | -------------------------------------------------------------------------------- | ----------- | | children | ReactNode | The content to render inside the simulator, typically a `` component. | None | | zIndex (optional) | number | The z-index value of the simulator so that it's displayed above layout elements. | `100` | | background (optional) | string | The background color of the simulator to match your website's design. | `"#ffffff"` | | className (optional) | string | A CSS class name to apply to the simulator container. | None | ## `enableAutoPreviews()` * **App Router:** Configures a Prismic client to automatically fetch draft content during a preview session. ```ts enableAutoPreviews({ client }); ``` > Projects [bootstrapped](https://prismic.io/docs/nextjs.md#install-prismic-and-slice-machine) with `@slicemachine/init` use this function in the generated `prismicio.ts`. | Parameter | Type | Description | Default | | --------- | ------ | ----------------- | ------- | | client | Client | A Prismic client. | None | * **Pages Router:** Configures a Prismic client to automatically fetch draft content during a preview session. ```ts enableAutoPreviews({ client, req, previewData }); ``` > Projects [bootstrapped](https://prismic.io/docs/nextjs.md#install-prismic-and-slice-machine) with `@slicemachine/init` use this function in the generated `prismicio.ts`. | Parameter | Type | Description | Default | | ---------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------- | ------- | | client | Client | A Prismic client. | None | | req (optional) | NextApiRequest | The request object from an [API Route](https://nextjs.org/docs/pages/building-your-application/routing/api-routes). | None | | previewData (optional) | object | The `previewData` object from `getStaticProps` or `getServerSideProps`. | None | ## `redirectToPreviewURL()` * **App Router:** Redirects a content writer to a previewed document's URL. This function should only be called in a Route Handler. ```ts redirectToPreviewURL({ client, request }); ``` > Projects [bootstrapped](https://prismic.io/docs/nextjs.md#install-prismic-and-slice-machine) with `@slicemachine/init` use this function in the generated `/api/preview` Route Handler. | Parameter | Type | Description | Default | | ----------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | client | Client | A Prismic client. | None | | request | NextRequest | The `request` object from a [Route Handler](https://nextjs.org/docs/app/building-your-application/routing/route-handlers). | None | | linkResolver (optional) | (field: ContentRelationshipField) => string \| null \| undefined | A [link resolver](https://prismic.io/docs/route-resolver.md#link-resolver) function used to determine a document's URL. If it returns it value, it takes priority over a [route resolver](https://prismic.io/docs/route-resolver.md). | None | | defaultURL (optional) | string | The default redirect URL if a URL cannot be determined for the previewed document. | `/` | * **Pages Router:** Redirects a content writer to a previewed document's URL. This function should only be called in an API Route. ```ts redirectToPreviewURL({ client, req, res }); ``` > Projects [bootstrapped](https://prismic.io/docs/nextjs.md#install-prismic-and-slice-machine) with `@slicemachine/init` use this function in the generated `/api/preview` API Route. | Parameter | Type | Description | Default | | ----------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | client | Client | A Prismic client. | None | | req | NextApiRequest | The `req` object from an [API Route](https://nextjs.org/docs/pages/building-your-application/routing/api-routes). | None | | res | NextApiResponse | The `res` object from an [API Route](https://nextjs.org/docs/pages/building-your-application/routing/api-routes). | None | | linkResolver (optional) | (field: ContentRelationshipField) => string \| null \| undefined | A [link resolver](https://prismic.io/docs/route-resolver.md#link-resolver) function used to determine a document's URL. If it returns it value, it takes priority over a [route resolver](https://prismic.io/docs/route-resolver.md). | None | | defaultURL (optional) | string | The default redirect URL if a URL cannot be determined for the previewed document. | `/` | | basePath (optional) | string | The `basePath` for the website as it is defined in `next.config.js`. | None | ## `exitPreview()` * **App Router:** Ends a Prismic preview by exiting Draft Mode. This function should only be called in a Route Handler. ```ts exitPreview(); ``` > Projects [bootstrapped](https://prismic.io/docs/nextjs.md#install-prismic-and-slice-machine) with `@slicemachine/init` use this function in the generated `/api/exit-preview` Route Handler. * **Pages Router:** Ends a Prismic preview by exiting Preview Mode. This function should only be called in an API Route. ```ts exitPreview({ req, res }); ``` > Projects [bootstrapped](https://prismic.io/docs/nextjs.md#install-prismic-and-slice-machine) with `@slicemachine/init` use this function in the generated `/api/exit-preview` API Route. | Parameter | Type | Description | Default | | --------- | --------------- | ----------------------------------------------------------------------------------------------------------------- | ------- | | req | NextApiRequest | The `req` object from an [API Route](https://nextjs.org/docs/pages/building-your-application/routing/api-routes). | None | | res | NextApiResponse | The `res` object from an [API Route](https://nextjs.org/docs/pages/building-your-application/routing/api-routes). | None | ## `setPreviewData()` > **Important** > > `setPreviewData()` is only used with the Pages Router. Sets data in Next.js' Preview Mode cookie needed to support content previews. This function should only be called in an API Route. ```ts setPreviewData({ req, res }); ``` > Projects [bootstrapped](https://prismic.io/docs/nextjs.md#install-prismic-and-slice-machine) with `@slicemachine/init` use this function in the generated `/api/preview` API Route. | Parameter | Type | Description | Default | | --------- | --------------- | ----------------------------------------------------------------------------------------------------------------- | ------- | | req | NextApiRequest | The `req` object from an [API Route](https://nextjs.org/docs/pages/building-your-application/routing/api-routes). | None | | res | NextApiResponse | The `res` object from an [API Route](https://nextjs.org/docs/pages/building-your-application/routing/api-routes). | None | ## ~~`createLocaleRedirect()`~~ > **Caution** > > `createLocaleRedirect()` was removed from `@prismicio/next` in v2. We learned it significantly slowed down websites. See [Replace `createLocaleRedirect()`](https://prismic.dev/msg/next/main/replace-createLocaleRedirect) for upgrade instructions. # Upgrade from v1 Follow these steps to upgrade an existing project to `@prismicio/next` v2. 1. **Install `@prismicio/next` v2** ```sh npm install @prismicio/next@^2 ``` 2. **Replace `CreateClientConfig` in `prismicio.ts`** > **Important** > > This step is only necessary for websites using the App Router. `CreateClientConfig` is deprecated when using the App Router; the `previewData` and `req` options do not apply. Use `@prismicio/client`'s `ClientConfig` instead. ```ts filename=prismicio.ts import { CreateClientConfig } from "@prismicio/next"; // [!code --] import { ClientConfig } from "@prismicio/client"; // [!code ++] export function createClient( config: CreateClientConfig = {}, // [!code --] config: ClientConfig = {}, // [!code ++] ) { const client = prismic.createClient(repositoryName, { // ... ...config, }); prismicNext.enableAutoPreviews({ client, previewData, req }); // [!code --] prismicNext.enableAutoPreviews({ client }); // [!code ++] return client; } ``` 3. **Update imports when using the Pages Router** > **Important** > > This step is only necessary for websites using the Pages Router. Change all imports from `@prismicio/next` to `@prismicio/next/pages`. ```ts import { PrismicNextImage } from "@prismicio/next"; // [!code --] // [!code word:/pages:1] import { PrismicNextImage } from "@prismicio/next/pages"; // [!code ++] ``` 4. **Replace `createLocaleRedirect()`** > **Important** > > This step is only necessary for websites using `createLocaleRedirect()`. See [Replace `createLocaleRedirect()`](https://prismic.dev/msg/next/main/replace-createLocaleRedirect) for upgrade instructions