A Deep Dive into Sanity's Visual Editing and Presentation Tool: The developer view

At Sanity Partners, we're passionate about advancing structured content and modern CMS experiences for teams and organizations. As an official Sanity agency partner, we help our clients get the most out of Sanity and the ecosystem around it.

We've also created an open-source project called CMS-Kit where we gather our expertise from building complex projects using Sanity. If you'd like to go beyond just reading about these features and want some hands-on experience using Sanity CMS, we offer a quick and easy way to try it out. Visit this page and fill out the form with your email. We'll spin up a personal demo project for you and send the invite straight to your inbox. In just a few seconds, you'll have your own Sanity Studio instance to explore, edit, and experiment with for two weeks.

CMS-Kit signup form

We're always eager to experiment with new features that improve the CMS and editing workflow. That's why whenever Sanity releases something new - like the Visual Editing and Presentation tool - we dive in, build with it, and share our findings with the community.

In this article, we'll walk you through the possibilities that these tools bring, our experience building with them, and how you can use them for your own projects.

Visual Editing and Presentation: An Overview

The Visual Editing feature in Sanity Studio has changed the content editing experience, making it more intuitive and interactive than ever. At the heart of this evolution is the Presentation tool - a powerful interface that complements the traditional Desk tool by offering a more visual and context-aware editing experience.

Sanity's presentation tool interface

Unlike the Desk Structure tool, which organizes content by document type, the Presentation tool puts the actual page front and center. This approach simplifies content management, supports a wide variety of content types, and gives editors a clearer view of how their changes affect the site's interface. The page rendered by your application is displayed directly within the CMS, and the presentation layer is now deeply integrated into many core CMS actions, making it a central component of Sanity Studio workflows.

On the right side, you'll see all the documents that provide content for the current page. Simply select a document to open a familiar editor form, where you can update its fields - changes are instantly reflected in your preview, making the editing process fast and visual.

The Presentation Tool: Key Features

The Presentation tool in Sanity Studio offers a solid set of features designed to improve visual editing and content management. Its top panel provides quick access to essential options for content editors, making workflows more intuitive and collaborative.

Sanity's presentation tool features

1. Visual Overlays

A dedicated switch allows you to enable or disable visual overlays on your page. When overlays are active, interactive highlights appear directly over content elements, making it easy to locate and edit the corresponding fields in Sanity Studio. This feature simplifies the process of identifying where content lives within your documents.

2. Published/Draft Mode

Toggle between viewing the published and draft versions of your content. This lets you verify ongoing edits against what's currently live, making sure that updates are accurate and ready before publishing.

3. Desktop/Mobile View

Switch between desktop and mobile device previews to see exactly how your content will display on different screens. This helps maintain consistency and quality across all device types.

Connected Documents & Editor Panel

On the right side of the interface, you'll see a column that adapts to your current context. At the root level, it displays all documents connected to the page you're previewing - such as headers, footers, and content blocks. Selecting any document opens the familiar editor form, allowing you to review and update content instantly. Any changes are reflected in the preview in real time.

The Magic of Overlays

Remember those head-scratching moments when you couldn't find a specific piece of text in your CMS, even though it was staring right at you on the page? Well, those days are long gone! Now, all it takes is a simple click. When you hover your mouse over any piece of content - be it plain text, formatted text, or even an image, you'll see a box overlay pop up, introducing you to the world of visual and intuitive editing.

This handy overlay feature on preview pages is your new best friend in visual editing and content management. It's a super useful and efficient way for you to pick out a specific piece of content and then directly open the studio to edit that particular field in the document.

Sanity visual editing overlays

It's especially handy with nested objects, where finding the right field can usually feel like looking for a needle in a haystack. With the overlay, this part gets much easier. Now you can just point, click, and get straight to what you want to change.

Setting Up the Presentation Tool

Configuring the Presentation tool in Sanity Studio is straightforward. To get started, follow these steps:

1. Update your Sanity Studio to the latest version
2. Import the Presentation tool in your configuration:
   import {presentationTool} from 'sanity/presentation'
3. Add presentationTool to your plugins array in sanity.config.ts, along with the required options
4. Connect your frontend application to Sanity for live previews and draft mode

// sanity.config.ts

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

export default defineConfig({
  // ... your config,
  plugins: [
    presentationTool({
      resolve,
      previewUrl: {previewMode: {enable: '/api/draft-mode/enable'}},
    }),
    // ... other plugins
  ],
})

• previewUrl: Defines the preview URL for your frontend application. The previewMode property specifies the endpoint for enabling draft mode.
• resolve: A function for document location resolution (more on this in the next section).

To support draft previews, your Next.js project needs an endpoint for draft mode. Here's a minimal example:

// app/api/draft-mode/enable.ts

import {client} from '@/sanity/lib/client'
import {token} from '@/sanity/lib/token'
import {defineEnableDraftMode} from 'next-sanity/draft-mode'

export const {GET} = defineEnableDraftMode({
  client: client.withConfig({token}),
})

This endpoint, powered by next-sanity, enables draft mode in your Next.js frontend. When invoked, it authenticates the request and switches the preview to show draft content. This integration is essential for a smooth content editing and live preview workflow within Sanity Studio.

Configuring Document Locations

The Presentation tool introduces the concept of Document Locations. This feature shows where a document is used across your interface, helping editors understand the impact of a single document change.

While the basic locate example is available in the Sanity documentation, here's how we set it up for more advanced cases.

We started by importing the necessary modules and defining both our main document routes and their locations:

/**
 * Sets up the Presentation Resolver API,
 * see https://www.sanity.io/docs/presentation-resolver-api for more information.
 */

import {resolveHref} from '@/sanity/lib/utils'
import {defineDocuments, defineLocations} from 'sanity/presentation'

export const mainDocuments = defineDocuments([
  {
    route: '/projects/:slug',
    filter: `_type == "project" && slug.current == $slug`,
  },
  {
    route: '/:slug',
    filter: `_type == "page" && slug.current == $slug`,
  },
])

export const locations = {
  settings: defineLocations({
    message: 'This document is used on all pages',
    tone: 'caution',
  }),
  home: defineLocations({
    message: 'This document is used to render the front page',
    tone: 'positive',
    locations: [{title: 'Home', href: resolveHref('home')!}],
  }),
  project: defineLocations({
    select: {title: 'title', slug: 'slug.current'},
    resolve: (doc) => ({
      locations: [
        {
          title: doc?.title || 'Untitled',
          href: resolveHref('project', doc?.slug)!,
        },
      ],
    }),
  }),
  page: defineLocations({
    select: {title: 'title', slug: 'slug.current'},
    resolve: (doc) => ({
      locations: [
        {
          title: doc?.title || 'Untitled',
          href: resolveHref('page', doc?.slug)!,
        },
      ],
    }),
  }),
}

It took some experimentation to get these configurations right, but the results were worth it! After adding this code, a new dropdown appeared in the form editor:

Sanity Studio 'used on page' references

From there, I can easily see where each document is used. With just one click, I can jump to the relevant page in the content management tool, observe the content, and preview any changes I make in real time.

Multiple Presentations: For Varied Purposes

You have the freedom to improve your studio by incorporating different Presentation tools and using them for various content types. This lets you improve your content management workflow and meet the specific requirements of different frontends. By creating separate Presentations for each frontend, you can personalize and customize your content to provide a smooth and personalized user experience. This single source of truth approach is beneficial for all content creators.

What is the underlying technology?

Several new technologies and methods were used to achieve the final result. A full explanation of these technologies would require a separate article, so we'll briefly discuss the main points of how it operates here.

Content Source Maps

This technology improves the standard response from Headless CMS when content is requested. In this scenario, we receive extra data along with the content itself, providing information on how the content is mapped to the fields and paths in the document schema from which it was obtained. This is required to later open these fields in Sanity Studio for editing. Sanity has developed a complete specification for the Content Source Maps format. It would be beneficial if this could be adopted by other Headless CMSs.

Steganographic content appending

Having Content Source Maps on the front end isn't enough. You need to link that data to specific content pieces that eventually appear on the page. Here, the library developed by Vercel in collaboration with Sanity, @vercel/stega, comes into play. It allows us to add to the standard text data containing page content, browser-unreadable characters that encode the needed information. So, every text piece or picture containing an alt, carries information about where this data is stored in the CMS. Alt tags are always added to images, right?

Overlays

Overlays consist of a small library that identifies all elements on a page containing steganographic inserts and renders them interactive. Hovering over such an element will display a pop-up rectangle suggesting interaction with this element. If this occurs on a separate page, such as a preview branch embedded in Vercel, clicking on this element will open Sanity Studio in a new tab, and the necessary document and the corresponding inserts within this document will be immediately accessible. If you're already within Sanity Studio - in the Presentation tool, clicking on the element will open the editor on the right side.

Conclusion

Sanity has long stood out as a flexible CMS with plenty of ways to extend it. New features are designed as customizable blocks, which provides developers with modular options. The platform's core functionality works out of the box without extensive configuration.

These updates focus on reducing the workload for content creators by introducing live editing and real-time previews with minimal setup requirements. At FocusReactive, we monitor developments in this space closely, as we work with teams who need platforms that balance usability with customization options.

As a Sanity agency, we work with teams moving to modern content setups. Whether you're switching from an old CMS or starting fresh, we can help you build something that actually works for your editors and scales with your needs. Feel free to reach out or grab a quick call if you want to chat about your project.