In-Website Preview

When working in the writing room, authors can preview their new content on their website without having to publish the document.

1. Include the Prismic Toolbar javascript file

Next you will need to include the Prismic toolbar scripts on every page of your website. This means including it on your 404 page!

You can find this script in your repository 'Settings' section, under the 'Previews' tab.

Settings > Previews > Script

This toolbar will add a preview cookie when a user hits the preview button. 

This cookie contains the preview ref needed to call the API and receive the proper content.

Note for Sharable Previews & unpublished previews

To guarantee that Sharable Previews and unpublished document previews work properly you must ensure that these scripts are included on every page of your website, including your 404/Page Not Found page. Otherwise these previews might not work.

2. Setup a preview environment

In your repository, head to the Settings / Previews. Add a site name and the domain for your website where you wish to preview your content. You can also add an optional Link Resolver route which you will learn more about in the next section.

The interface for adding a new preview in Prismic

Note that you can also enter localhost domains such as:


If you are using our official Prismic javascript development kit (prismic-javascript), then that is all you need to do to gain the basic functionality of the Preview feature! If you are not using this kit to make your queries, then refer to the "Use the correct ref" section below.

With the basic functionality of the Preview feature, when you click on the preview button, you will be taken to the homepage of your preview domain. From here you can navigate to the page you are trying to preview.

Next we will show you how to add a Link Resolver endpoint so that you will be taken directly to the page you are trying to preview.

In order to be taken directly to the page you are previewing instead of the homepage, you need to add a Link Resolver endpoint. A typical example of this would be:


In your preview settings add this endpoint to the optional Link Resolver field.

Where to add a Link Resolver endpoint for your preview in Prismic

Using the official Prismic React.js starter project?

If you are using the official Prismic React.js starter project, then you should already have all the code in place you need for In-website previews. That's as much as you need to do!

If you're not using the official Prismic project, then follow the rest of the steps below.

Now you need to add the Link Resolver endpoint route to your website router.

import React from 'react'
import {
} from 'react-router-dom'
import Preview from './Preview'
import NotFound from './NotFound'
const App = () => (
      {/* Add the new preview route here */}
      <Route exact path='/preview' component={Preview} />
      <Route component={NotFound} />
export default App

You can see that when the "/preview" route is called, it will use the Preview component. Let's create this component now.

Add the Preview component

The Preview component must do the following:

  • Retrieve the preview token from the token parameter in the query string
  • Retrieve the documentId from the query string
  • Call the Prismic development kit with this token and the Link Resolver will retrieve the correct URL for the document being previewed
  • Redirect to the given URL

The Preview Token

Note that the preview token will be a URL. You DO NOT need to follow this url.

Processing the Preview Token with 'getPreviewResolver' method

All you need to do is pass the token into the getPreviewResolver method as shown below. (prismic-javascript kit V3.0.1 and above). Here is an example of what the Preview component might look like.

import { useEffect } from 'react';
import qs from 'qs';
import Prismic from 'prismic-javascript';
import { linkResolver } from './path/to/the/link-resolver.js';

const apiEndpoint = '';
const client = Prismic.client(apiEndpoint);
const Preview = ({ history, location }) => {
  useEffect(() => {
    const {token, documentId} = qs.parse(;
    if (!token) {
      return console.warn(`No token available, check your configuration`);
    client.getPreviewResolver(token, documentId).resolve(linkResolver, '/').then(url => history.push(url));
  return null;

export default Preview;

The Link Resolver function

This requires the use of a Link Resolver function so that the preview endpoint knows where to redirect to. You can learn more about link resolving by checking out the Link Resolving page.

You either need to define the Link Resolver in the Preview component or import it.

Deprecated 'previewSession' method

For anyone using a version of the prismic-javascript kit older than V3.0.1, then you should pass this token into the previewSession method as shown below.

import { useEffect } from 'react'
import qs from 'qs'
import Prismic from 'prismic-javascript'
import { linkResolver } from './path/to/the/link-resolver.js'

const apiEndpoint = ''
const client = Prismic.client(apiEndpoint)

const Preview = ({ history, location }) => {
  useEffect(() => {
    const params = qs.parse(
    if (!params.token) {
      return console.warn(`No token available, check your configuration`)

    client.previewSession(params.token, linkResolver, '/')
      .then(url => history.push(url))
  return null

export default Preview

4. Use the correct reference

Are you using the prismic-javascript library?

This last step is only required if you are not using the prismic-javascript library to retrieve your API object.

If you are using the Prismic.getApi method to retrieve your API object, then the correct reference will automatically be used and this last step is not necessary. If you are not using this method, then do the following:

When you preview your website, a preview cookie is generated that contains the preview token. This token can be used as a valid ref to make Prismic API queries. For any query you make on your website, make sure to check for the Preview cookie and use this preview ref in the query options if the preview cookie exists.

Here is how to retrieve the correct ref:

import Cookies from 'js-cookie';
import Prismic from 'prismic-javascript';

const previewRef = Cookies.get(Prismic.previewCookie);
const masterRef = api.refs.find(ref => { return ref.isMasterRef === true }).ref;
const ref = previewRef || masterRef;

Then here is an example that shows how to use this ref in your query:

// Then in your query, specify the ref like this
api.query('document.type', 'blog_post'),
  { ref }
).then(function(response) {
  // response is the response object, response.results holds the documents

And you're all set!

The preview functionality should now be all set on your project.

It's worth noting that the examples on this page are meant to be as simple as possible for this explanation. There are best practices that you can follow to better organize your project. We suggest exploring our React Starter Project to see how you might better set up your Preview functionality.

5. Troubleshooting

Mistakes happen. So sometimes you might to do a little troubleshooting to figure out where exactly the problem is from, luckily we've created an article for just that.