Implement the preview feature with the REST API

This page shows you how to get the preview reference and preview your content.

The preview works by using a preview token: when a user requests a preview from the Writing Room, a temporary and secure ref is generated for the preview session. Your website can then use this temporary ref to query the Prismic API. It will allow your website to display pending changes.

Additionally the Prismic script automatically detects when a user is browsing the website in a preview session, and displays the preview bar.

All the required code is already available out-of-the-box in our starter projects, but if you want to include it into a custom development, here are the 4 simple steps to integrate it into your website.

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

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 to add a new preview in Prismic

Note that you can also enter localhost domains such as:


3. Use the preview token as ref when available to make your queries

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 an example of how to retrieve the correct ref in Node.js:

var Cookies = require('cookies');

// Example ref selection for NodeJS with ExpressJS
const cookies = new Cookies(req, res);
const previewRef = cookies.get(Prismic.previewCookie);
const masterRef = api.refs.find(ref => { return ref.isMasterRef === true; });
const ref = previewRef || masterRef.ref;

Then here is an example that shows how to use this ref when constructing your api query:


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 in the Prismic interface

Now you need to add the Link Resolver endpoint in your website application.

This is a special URL of your website that Prismic will call to request a preview, passing the preview token in the query string. When requested this endpoint must:

  • Retrieve the preview token from the token parameter in 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

Here's an example of what this would look like if developing a NodeJS website:

// Example preview endpoint for NodeJS with ExpressJS 
const Prismic = require('prismic-javascript');
const linkResolver = require('./path/to/the/link-resolver.js');
const apiEndpoint = '';
app.get('/preview', function (req, res) {
  const token = req.query.token;
  Prismic.getApi(apiEndpoint, { req: req })
    .then((api) => api.previewSession(token, linkResolver, '/'))
    .then((url) => {
      res.redirect(302, url);

And with that you should have everything in place that you need to begin previewing your content!

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.