@sanity/overlays — Visual Editing
Sanity Visual Editing highlights elements on your website that are editable in Sanity Studio.
Learn more about this feature, and how to use it, in our Visual Editing documentation.
Note
Visual Editing requires Content Source Maps, a feature available on a Sanity Enterprise plan. If you are an existing enterprise customer, contact our sales team to have Content Source Maps enabled on your project. Learn more about Sanity for Enterprise organizations here.
Note
This package is not required for Vercel Visual Editing. It is only required if you want to enable visual editing on alternative hosting providers.
Prerequisites
- Sanity Enterprise project with Content Source Maps enabled
- An enhanced Sanity Client using
createClient
from @sanity/preview-kit
or next-sanity
with encodeSourceMap
and studioUrl
enabled
Getting started
1. Install @sanity/overlays
Install the package along with either next-sanity
or @sanity/preview-kit
depending on your project.
The other peer dependencies are required and will be loaded asynchronously when Visual Editing is enabled.
npm install @sanity/overlays next-sanity react react-dom react-is styled-components
npm install @sanity/overlays @sanity/preview-kit react react-dom react-is styled-components
2. Configure an enhanced Sanity client
Visual Editing relies on encoded metadata being present in values returned from your queries. This metadata is only present when using an enhanced Sanity client on a project on which Content Source Maps is enabled.
Ensure encodeSourceMap
is only true
in non-production environments.
import { createClient } from 'next-sanity'
import { createClient } from '@sanity/preview-kit/client'
const client = createClient({
studioUrl: '/studio',
encodeSourceMap: true,
})
For more configuration options when working with Content Source Maps and the enhanced Sanity Client, see the README's of either package:
3. Dynamically enable Visual Editing
Ensure the overlay is only enabled in non-production environments.
import { enableVisualEditing } from '@sanity/overlays'
const disable = enableVisualEditing()
disable()
In React you could enable the feature in a useEffect()
hook, where disable()
will run on unmount:
import { enableVisualEditing } from '@sanity/overlays'
useEffect(enableVisualEditing, [])
When enabled, you should see clickable "Edit in Sanity Studio" buttons for every element which contains encoded metadata from Content Source Maps.
Manually configuring "Edit in Sanity Studio" elements
data-sanity-edit-target
You can choose which element to render the "Edit in Sanity Studio" buttons on by adding a data-sanity-edit-target
attribute to the element you want to be clickable. This allows you to move the edit container to a parent wrapper element.
In this example, by default the edit button would be placed on the <h1>
tag
<section>
<h1>{dynamicTitle}</h1>
<div>Hardcoded Tagline</div>
</section>
But by adding the data-sanity-edit-target
attribute to the <section>
tag, the edit button will be placed on it instead.
<section data-sanity-edit-target>
<h1>{dynamicTitle}</h1>
<div>Hardcoded Tagline</div>
</section>
Manually setting the edit target will use the first element it finds with encoded metadata and remove clickable buttons from all other child elements.
data-sanity-edit-info
You can manually add custom "Edit in Sanity Studio" elements by adding a data-sanity-edit-info
attribute to the element you want to be editable.
export function MyComponent() {
return (
<div
data-sanity-edit-info={JSON.stringify({
origin: 'sanity.io',
href: '/studio',
})}
>
...
</div>
)
}