Live Preview

With Live Preview you can render your front-end application directly within the Admin Panel. As you type, your changes take effect in real-time. No need to save a draft or publish your changes. This works in both Server-side as well as Client-side environments.

Live Preview works by rendering an iframe on the page that loads your front-end application. The Admin Panel communicates with your app through window.postMessage events. These events are emitted every time a change is made to the Document. Your app then listens for these events and re-renders itself with the data it receives.

To add Live Preview, use the admin.livePreview property in your Payload Config:

1import { buildConfig } from 'payload'
2
3const config = buildConfig({
4  // ...
5  admin: {
6    // ...
7    livePreview: {
8      url: 'http://localhost:3000',
9      collections: ['pages']
10    },
11  }
12})

Options

Setting up Live Preview is easy. This can be done either globally through the Root Admin Config, or on individual Collection Admin Configs and Global Admin Configs. Once configured, a new "Live Preview" tab will appear at the top of enabled Documents. Navigating to this tab opens the preview window and loads your front-end application.

The following options are available:

Path	Description
`url` *	String, or function that returns a string, pointing to your front-end application. This value is used as the iframe `src`. More details.
`breakpoints`	Array of breakpoints to be used as “device sizes” in the preview window. Each item appears as an option in the toolbar. More details.
`collections`	Array of collection slugs to enable Live Preview on.
`globals`	Array of global slugs to enable Live Preview on.

* An asterisk denotes that a property is required.

URL

The url property resolves to a string that points to your front-end application. This value is used as the src attribute of the iframe rendering your front-end. Once loaded, the Admin Panel will communicate directly with your app through window.postMessage events.

To set the URL, use the admin.livePreview.url property in your Payload Config:

1import { buildConfig } from 'payload'
2
3const config = buildConfig({
4  // ...
5  admin: {
6    // ...
7    livePreview: {
8      url: 'http://localhost:3000', 
9      collections: ['pages'],
10    },
11  }
12})

Dynamic URLs

You can also pass a function in order to dynamically format URLs. This is useful for multi-tenant applications, localization, or any other scenario where the URL needs to be generated based on the Document being edited.

To set dynamic URLs, set the admin.livePreview.url property in your Payload Config to a function:

1import { buildConfig } from 'payload'
2
3const config = buildConfig({
// ...
admin: {
  // ...
  livePreview: {
    url: ({
      data,
      documentInfo,
      locale
    }) => `${data.tenant.url}${ // Multi-tenant top-level domain
      documentInfo.slug === 'posts' ? `/posts/${data.slug}` : `${data.slug !== 'home' : `/${data.slug}` : ''}`
    }${locale ? `?locale=${locale?.code}` : ''}`, // Localization query param
    collections: ['pages'],
  },
}
18})

The following arguments are provided to the url function:

Path	Description
`data`	The data of the Document being edited. This includes changes that have not yet been saved.
`locale`	The locale currently being edited (if applicable). More details.
`collectionConfig`	The Collection Admin Config of the Document being edited. More details.
`globalConfig`	The Global Admin Config of the Document being edited. More details.
`req`	The Payload Request object.

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:

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

Breakpoints

The breakpoints property is an array of objects which are used as “device sizes” in the preview window. Each item will render as an option in the toolbar. When selected, the preview window will resize to the exact dimensions specified in that breakpoint.

To set breakpoints, use the admin.livePreview.breakpoints property in your Payload Config:

1import { buildConfig } from 'payload'
2
3const config = buildConfig({
// ...
admin: {
  // ...
  livePreview: {
    url: 'http://localhost:3000',
    breakpoints: [
      {
        label: 'Mobile',
        name: 'mobile',
        width: 375,
        height: 667,
      },
    ],
  },
}
19})

The following options are available for each breakpoint:

Path	Description
`label` *	The label to display in the drop-down. This is what the user will see.
`name` *	The name of the breakpoint.
`width` *	The width of the breakpoint. This is used to set the width of the iframe.
`height` *	The height of the breakpoint. This is used to set the height of the iframe.

* An asterisk denotes that a property is required.

The "Responsive" option is always available in the drop-down and requires no additional configuration. This is the default breakpoint that will be used on initial load. This option styles the iframe with a width and height of 100% so that it fills the screen at its maximum size and automatically resizes as the window changes size.

You may also explicitly resize the Live Preview by using the corresponding inputs in the toolbar. This will temporarily override the breakpoint selection to "Custom" until a predefined breakpoint is selected once again.

If you prefer to freely resize the Live Preview without the use of breakpoints, you can open it in a new window by clicking the button in the toolbar. This will close the iframe and open a new window which can be resized as you wish. Closing it will automatically re-open the iframe.

Example

For a working demonstration of this, check out the official Live Preview Example.

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."

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.

Live Preview

Options

URL

Dynamic URLs

Breakpoints

Example

Implementing Live Preview in your frontend

Related Help Topics