Preview

Preview is a feature that allows you to generate a direct link to your front-end application. When enabled, a "preview" button will appear on the Edit View within the Admin Panel with an href pointing to the URL you provide. This will provide your editors with a quick way of navigating to the front-end application where that Document's data is represented. Otherwise, they'd have to determine that URL themselves which is not always straightforward especially in complex apps.

The Preview feature can also be used to achieve something known as "Draft Preview". With Draft Preview, you can navigate to your front-end application and enter "draft mode", where your queries are modified to fetch draft content instead of published content. This is useful for seeing how your content will look before being published. More details.

To add Preview, pass a function to the admin.preview property in any Collection Config or Global Config:

1import type { CollectionConfig } from 'payload'
2
3export const Pages: CollectionConfig = {
slug: 'pages',
admin: {
  preview: ({ slug }) => `http://localhost:3000/${slug}`,
},
fields: [
  {
    name: 'slug',
    type: 'text',
  },
],
14}

Options

The preview function resolves to a string that points to your front-end application with additional URL parameters. This can be an absolute URL or a relative path, and can run async if needed.

The following arguments are provided to the preview function:

Path	Description
`doc`	The data of the Document being edited. This includes changes that have not yet been saved.
`options`	An object with additional properties.

The options object contains the following properties:

Path	Description
`locale`	The current locale of the Document being edited.
`req`	The Payload Request object.
`token`	The JWT token of the currently authenticated user.

If your application requires a fully qualified URL, such as within deploying to Vercel Preview Deployments, you can use the req property to build this URL:

1preview: (doc, { req }) => `${req.protocol}//${req.host}/${doc.slug}` 

Draft Preview

The Preview feature can be used to achieve "Draft Preview". After clicking the preview button from the Admin Panel, you can enter into "draft mode" within your front-end application. This will allow you to adjust your page queries to include the draft: true param. When this param is present on the request, Payload will send back a draft document as opposed to a published one based on the document's _status field.

To enter draft mode, the URL provided to the preview function can point to a custom endpoint in your front-end application that sets a cookie or session variable to indicate that draft mode is enabled. This is framework specific, so the mechanisms here vary from framework to framework although the underlying concept is the same.

Next.js

If you're using Next.js, you can do the following code to enter Draft Mode.

Step 1: Format the Preview URL

First, format your admin.preview function to point to a custom endpoint that you'll open on your front-end. This URL should include a few key query search params:

1import type { CollectionConfig } from 'payload'
2
3export const Pages: CollectionConfig = {
slug: 'pages',
admin: {
  preview: ({ slug }) => {
    const encodedParams = new URLSearchParams({
      slug,
      collection: 'pages',
      path: `/${slug}`,
      previewSecret: process.env.PREVIEW_SECRET || '',
    })
13
    return `/preview?${encodedParams.toString()}` 
  },
},
fields: [
  {
    name: 'slug',
    type: 'text',
  },
],
23}

Step 2: Create the Preview Route

Then, create an API route that verifies the preview secret, authenticates the user, and enters draft mode:

/app/preview/route.ts

1import type { CollectionSlug, PayloadRequest } from 'payload'
2import { getPayload } from 'payload'
3
4import { draftMode } from 'next/headers'
5import { redirect } from 'next/navigation'
6
7import configPromise from '@payload-config'
8
9export async function GET(
10  req: {
11    cookies: {
12      get: (name: string) => {
13        value: string
14      }
15    }
16  } & Request,
17): Promise<Response> {
18  const payload = await getPayload({ config: configPromise })
19
20  const { searchParams } = new URL(req.url)
21
22  const path = searchParams.get('path')
23  const collection = searchParams.get('collection') as CollectionSlug
24  const slug = searchParams.get('slug')
25  const previewSecret = searchParams.get('previewSecret')
26
27  if (previewSecret !== process.env.PREVIEW_SECRET) {
28    return new Response('You are not allowed to preview this page', {
29      status: 403,
30    })
31  }
32
33  if (!path || !collection || !slug) {
34    return new Response('Insufficient search params', { status: 404 })
35  }
36
37  if (!path.startsWith('/')) {
38    return new Response(
39      'This endpoint can only be used for relative previews',
40      { status: 500 },
41    )
42  }
43
44  let user
45
46  try {
47    user = await payload.auth({
48      req: req as unknown as PayloadRequest,
49      headers: req.headers,
50    })
51  } catch (error) {
52    payload.logger.error(
53      { err: error },
54      'Error verifying token for live preview',
55    )
56    return new Response('You are not allowed to preview this page', {
57      status: 403,
58    })
59  }
60
61  const draft = await draftMode()
62
63  if (!user) {
64    draft.disable()
65    return new Response('You are not allowed to preview this page', {
66      status: 403,
67    })
68  }
69
70  // You can add additional checks here to see if the user is allowed to preview this page
71
72  draft.enable()
73
74  redirect(path)
75}

Step 3: Query Draft Content

Finally, in your front-end application, you can detect draft mode and adjust your queries to include drafts:

/app/[slug]/page.tsx

1export default async function Page({ params: paramsPromise }) {
const { slug = 'home' } = await paramsPromise
3
const { isEnabled: isDraftMode } = await draftMode()
5
const payload = await getPayload({ config })
7
const page = await payload.find({
  collection: 'pages',
  depth: 0,
  draft: isDraftMode, 
  limit: 1,
  overrideAccess: isDraftMode,
  where: {
    slug: {
      equals: slug,
    },
  },
})?.then(({ docs }) => docs?.[0])
20
if (page === null) {
  return notFound()
}
24
return (
  <main>
    <h1>{page?.title}</h1>
  </main>
)
30}

Conditional Preview URLs

You can also conditionally enable or disable the preview button based on the document's data. This is useful for scenarios where you only want to show the preview button when certain criteria are met.

To do this, simply return null from the preview function when you want to hide the preview button:

1import type { CollectionConfig } from 'payload'
2
3export const Pages: CollectionConfig = {
slug: 'pages',
admin: {
  preview: (doc) => {
    return doc?.enabled ? `http://localhost:3000/${doc.slug}` : null
  },
},
fields: [
  {
    name: 'slug',
    type: 'text',
  },
  {
    name: 'enabled',
    type: 'checkbox',
  },
],
20}

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.