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.
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.
Protip
Sanity's Visual Editing tooling is available on all plans, including free, and supported by most modern frameworks and hosting platforms.
Note that some hosting platforms, like Vercel, have Visual Editing offerings with platform-specific features. Sanity's tooling should also be compatible with these solutions as long as they are based on Content Source Maps.
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 that 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
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.
Visual Editing depends on your front end rendering draft content for users that are authenticated through your Sanity project:
- 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.
- 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.
- 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 simpler 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 websites 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.
Sanity Studio comes with an out-of-the-box tool that lets you load a website within and control
- Add the Presentation tool that comes included in the
sanity
package - Configure it with:
- The
previewURL
, most often the root URL for your production site - The
resolver
APIs, 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).
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
- How to set up the resolver APIs
- Conceptual documentation for Loaders, Overlays, and Stega-encoding
You can visit the Visual Editing Resources article to find links to starter templates, framework-specific guides, and tooling.