✨Discover storytelling in the AI age with Pixar's Matthew Luhn at Sanity Connect, May 8th—register now

Introduction to Visual Editing

Introduction to Sanity's Visual Editing features, architecture, and where to go to learn more.

This article will give you a high-level overview of the different capabilities and components that make for the Sanity Visual Editing experience. This is an excellent place to start if you want to implement Visual Editing.

What is Visual Editing?

Visual Editing is an umbrella term that Sanity uses for the different features that make it possible for content creators to work with content in the context of a visual presentation.

Sanity’s Visual Editing experience offers:

  • Global preview with immediate visual feedback on changes across all documents
  • Overlays — clickable visual indicators in a presentation that let you quickly get to exactly where some content can be edited
  • The Presentation tool for Sanity Studio brings content previews and click-to-edit into the editing environment and makes it easy to jump between editing modes

Sanity’s tooling for Visual Editing has been designed in a way that allows you to:

  • Have a global responsive preview of your site and across all documents in use instead of the preview being limited to a page or specific components
  • Use your preferred component system and framework; you do not have to opt into an opinionated component system.
  • Put your production site in a preview mode, eliminating the need to set up dedicated preview branches and builds
  • Integrate preview functionality without bloating the production build; only load the necessary dependencies for authenticated users in preview mode

Getting Started with Visual Editing

To implement Visual Editing, you must add support for loading draft content into your front end and setting up the Presentation tool that embeds your front end in preview mode.

In your front end(s)

Visual Editing depends on your front end rendering draft content for users that are authenticated through your Sanity project:

  1. Add a Loader or configure the Refresh API, often found in Sanity’s framework-specific tooling, to load all the draft content across your dataset in preview mode or the published content in production.
  2. Enable Overlays for the click-to-edit functionality, often done with out-of-the-box Stega-encoded text strings or by adding Content Source Maps as data attributes to the elements you want to be clickable.
  3. Make it possible to enable (and disable) preview mode for authenticated users, most often by setting a cookie via a serverless function.

The specifics of how you enable the Visual Editing in front ends depend on how the framework accommodates data fetching:

  • Statically rendered during deployment
  • Server-side rendering with route-based caching
  • Hybrid/isomorphic with both server-side and client-side rendering
  • Client-side rendering, also known as Single Page Application

Visual Editing is designed to work with all these modes except statically generated websites. The rendering capabilities of the framework determine how fast your previews can be and how simple the implementation is:

  • Low-latency content previews work best for frameworks that support client-side rehydration. Require setting up a client-side loader.
  • It's easier to set up server-side preview, with the trade-off that previews are a bit slower (seconds instead of milliseconds). Requires the Refresh API.
  • For front ends that are statically generated, the best approach is to set up a server-side rendered preview deployment if the framework supports it or a preview deployment that uses the previewDrafts perspective when querying for data.

In your Sanity Studio

Sanity Studio comes with an out-of-the-box tool that lets you load a website within and control

  1. Add the Presentation tool that comes included in the sanity package
  2. Configure it with:
  • The previewURL, most often the root URL for your production site
  • The locate API, where you add the logic that lets content creators see and open all locations where a specific document is in use

Protip

You can add multiple Presentation tool configurations to accommodate multiple front end presentations (for example: for a website and for a newsletter web preview).

Resources

There are different ways of getting started with Visual Editing, depending on how you prefer to learn and what framework you use in the front end.

This documentation gives a high-level overview and introduction to the different aspects and concepts of Visual Editing:

  • Documentation for configuring the Presentation tool and its locate API
  • Conceptual documentation for Overlays and Loaders

You can visit the Visual Editing Resources article to find links to starter templates, framework-specific guides, and tooling.

Was this article helpful?