🔮 Sanity Create is here. Writing is reinvented. Try now, no developer setup

Configuring 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 for Sanity Studio enables the integrated Visual Editing experience with live previews and click-to-edit.

This article focuses on the configuration of the Presentation tool for Sanity Studio. Below are relevant resources for learning how visual editing works conceptually, and how to set it up with a specific framework.

Prerequisites

To use the Presentation tool, you have to upgrade your Studio‘s sanity dependency to v3.40.0 or preferably latest.

npm install sanity@latest

Configuration

Similarly to the Structure tool (formerly known as the Desk tool), you add Presentation to your Studio's configuration file (code example below).

Basic configuration

  1. Import presentationTool from sanity/presentation
  2. Add it to the plugins array
  3. Add the base URL for your front end to the previewUrl attribute
// sanity.config.ts
import {defineConfig} from 'sanity'
import {presentationTool} from 'sanity/presentation'
// ...other imports // We recommend configuring the preview location base URL using // environment variables to support multiple environments
const SANITY_STUDIO_PREVIEW_URL = (
process.env.SANITY_STUDIO_PREVIEW_URL
|| 'http://localhost:3000'
)
export default defineConfig({ // Your configuration for the project ... plugins: [ // Add 'presentationTool' to the 'plugins' array
presentationTool({
// Required: set the base URL to the preview location in the front end
previewUrl: SANITY_STUDIO_PREVIEW_URL,
}),
// ...other plugins ], })

Configuration reference

The Presentation tool takes the following configuration attributes:

  • REQUIREDpreviewUrlstring

    The relative or absolute path to the base location in the front end you want to enable in the Presentation tool. If your Studio shares the same base URL as your front end, you can use relative URLs. We recommend implementing this as an environment variable to make it easier to work in development and production.

    Examples:

    • http://localhost:3000
    • https://your-production-url.com/
    • /

    You may also 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

    Examples: presentation, preview, website, app

  • 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

    Examples: Website Preview, Newsletter Preview, US Site Preview

  • locate (deprecated)Observable<DocumentLocationsState>

    This property has been depreacted and replaced by the new location resolver API.

  • 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 stablizes.

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.

Was this article helpful?