Skip to content
Unlock seamless workflows and faster delivery with our latest releases - Join the deep dive

The Presentation tool

The Presentation tool enables Visual Editing for interactive live previews. This is how you set it up within your studio.

The Presentation Tool enables Visual Editing by integrating a live preview of your web application within Sanity Studio.

It provides:

  • Live preview: See draft content updates in real-time within the Studio
  • Click-to-edit: Interactive overlays that help content creators find and edit the right fields
  • Page building: Advanced capabilities for adding, moving, and removing content sections
  • Preview sharing: A way for content creators to share a preview with others
  • Locations: Add shortcuts to open preview where a document is used from the Structure tool

For Studio-user friendly documentation, go to the user guide of the Presentation tool.

The Presentation tool is the primary way content editors experience Visual Editing

Prerequisites

To use the Presentation tool, your studio must be updated to v3.40.0 or preferably latest.

npm install sanity@latest

Protip

You must also add Visual Editing support into your front-end application.

We recommend exploring the implementation guides (located in the left-side navigation), these will also take you through setting up the Presentation tool.

Configuration steps

Similarly to the other tools and plugins, you add the Presentation tool to your main studio configuration file. The example below shows a typical setup for a Next.js project where specific endpoints are supplied to let Sanity Studio put the front end into preview mode.

Basic configuration

  1. Import presentationTool from sanity/presentation
  2. Add it to the plugins array
  3. Add your frontend-specific details, such as the origin URL and endpoints for enabling or disabling preview mode
// sanity.config.ts
// ...all other imports

import { presentationTool } from 'sanity/presentation'


export default defineConfig({
  // ... all other config settings
  plugins: [
    // ...all other plugins

    presentationTool({

      previewUrl: {

        origin: 'https://my-cool-site.com',

        previewMode: {

          enable: '/api/draft-mode/enable',

          disable: '/api/draft-mode/disable',

        },

      },

    }),
  ],
})

Protip

If you are working with an embedded studio you can skip the origin property on line 10 of the example.

Map content to front-end routes with locations resolver function

To map Sanity documents to their corresponding front-end routes, create a locations resolver function. This function tells the Presentation Tool how each document type corresponds to a route in the front end.

The locations resolver lets the studio know where content appears in front end

Add route definitions for your document types

In the example below, we map documents of type product to /products/${slug} and add them to the top-level index. You will need to substitute your own types and routes as appropriate.

// ./lib/presentation/resolve-production-url.ts
import {defineLocations} from 'sanity/presentation'

export default defineLocations({
  // Map document types to frontend routes
  product: {
    select: {title: 'title', slug: 'slug.current'},
    resolve: (doc) => ({
      locations: [
        {title: doc.title, href: `/products/${doc.slug}`},
        {title: 'Products Index', href: `/products`},
      ],
    }),
  },
  // ...
})

Import the resolver function into sanity.config.ts and pass it to the presentationTool config

import {defineConfig} from 'sanity'
import {presentationTool} from 'sanity/presentation'

import resolveProductionUrl from './lib/presentation/resolve-production-url'


export default defineConfig({
  // ...
  plugins: [
    presentationTool({

      resolve: resolveProductionUrl,

      previewUrl: {
        origin: 'https://my-cool-site.com',
        previewMode: {
          enable: '/api/draft-mode/enable',
          disable: '/api/draft-mode/disable',
        },
      },
    }),
  ],
})

Configuration reference

The Presentation tool takes the following configuration attributes:

  • previewUrlstring | PreviewUrlOption

    Accepts an object with keys for setting the origin URL of your front end, as well as defining endpoints for enabling or disabling preview mode in your front end. Also accepts a plain string in the shape of a URL for projects that don't need the detailed setup.

    Read more about how to configure the Presentation tool to handle enabling/disable draft automatically.

  • iconReact component

    Sets an icon to represent the Presentation tool in the Studio's navigation bar. To use Sanity icons, install the @sanity/icons package.

  • namestring

    Sets a name for the Presentation tool. It's not visually represented in the Studio UI, but it’s included in the Studio's URL for the Presentation tool.

    This is useful if you want to implement multiple instances of Presentation, for example, for different channels, domains, or preview environments.

    Default value: presentation

  • titlestring

    Sets the title that is displayed in the Studio's navigation bar. Keep it short and descriptive to help editorial users understand what they can do with the tool.

    Default value: Presentation

  • resolvemainDocuments | locations

    Return the document-to-URL mapping to add affordances to quickly open documents in the Presentation tool. Go to the Presentation Resolver API documentation to learn more.

Mount a custom navigator component

Optionally, you can enhance the Presentation tool with a custom document navigator component to help users select different documents or views in the front-end UI.

Unstable feature

unstable_navigator has the unstable prefix because the API is likely to change. Don’t use it in a production environment unless you are ready to change it when the API stabilizes.

Example:

// Import your custom navigator component
import {NavigatorComponent} from './presentation/NavigatorComponent'

export default defineConfig({
  // Your configuration for the project
  // ...

  plugins: [
    presentationTool({
      // ...
      component: {
  			// Pass the custom component to the plugin
        unstable_navigator: NavigatorComponent
      },
    })
  ],
})

Navigator properties

  • REQUIREDcomponentReact component

    Specifies the navigator component to use with the Presentation tool. The component specified will be rendered as the content of the navigator panel.

  • minWidthnumber

    Sets the minimum width of the navigator component when it’s rendered in the UI. For the component to render, its value must be > 0 and other than null.

  • maxWidthnumber

    Sets the maximum width of the navigator component when it’s rendered in the UI. For the component to render, its value must be > 0 and other than null.

Updated on November 20, 2024

Was this article helpful?