Vercel Visual Editing > How to use Vercel visual editing

Vercel Visual Editing is an exciting feature offered by Vercel's site preview. It enhances your website by adding clickable links to any content present in the page that's coming from your DatoCMS project. By simply clicking on these links, you'll be seamlessly directed to the corresponding record in DatoCMS.

Once configured for your project, the implementation will resemble the following example:

How does it work?

When Vercel Visual Editing is enabled, DatoCMS's Content Delivery API incorporates hidden metadata into the response of the GraphQL queries you make.

This is achieved through a smart technique known as steganography. Steganography is the practice of concealing information within other data, and in this case, it involves encoding the metadata into invisible Unicode characters that are added to the existing strings — you can examine the complete encoding/decoding algorithm in the @vercel/stega NPM pagkage.

Once the "augmented strings" coming from DatoCMS are used in your pages, Vercel can locate and identify the hidden metadata in the final HTML, and display clickable links that direct you to the corresponding record in DatoCMS.

Which GraphQL fields support Visual Editing?

Currently, the metadata required to show a clickable link on Vercel is added in the following parts of the GraphQL response:

• Text fields (both Single-line Strings and Multi-paragraph Text) that are not empty and with no format validation: the metadata will be appended at the end of the original string;

• Structured Text fields: the metadata will be appended at the end of the last span node contained in the first paragraph, heading, list, code or blockquote node found in the document;

• The alt field of any Upload referenced in the response: the metadata will be appended at the end of the original string;

We've been conservative in deciding in which cases to embed hidden metadata, so your website should not break when enabling Visual Editing, but still, it's crucial that you test it thoroughly. If you encounter any problem, please refer to the Troubleshooting section of this guide.

Enabling Visual Editing

To leverage the powerful capabilities of Visual Editing, you can follow these straightforward steps to ensure its seamless integration into your workflow:

Step 1: Request activation of Visual Editing

If you're an Enterprise customer of both DatoCMS and Vercel, please contact us at support@datocms.com: by providing the ID of the project where you want to enable visual editing, we'll be able to switch on the feature rapidly.

Step 2: Add the Visual Editing headers to your GraphQL API calls

To communicate to DatoCMS's Content Delivery API that you want visual editing metadata included in your responses, you must add two headers to your API requests:

• X-Visual-Editing is the header that enables the feature, and it must be set to vercel-v1;

• X-Base-Editing-Url is required to generate the right link to your DatoCMS project: it's the base URL of the project on the CMS, and unless you're using a custom domain, it looks like https://example-project.admin.datocms.com

Here is an example of how to add the headers when using the standard fetch API. In this case, we're going to enable visual editing on every preview deployment of the website:

const visualEditingHeaders = process.env.VERCEL_ENV === "preview" ? {
  "X-Visual-Editing": "vercel-v1",
  "X-Base-Editing-Url": "https://<YOUR-PROJECT-NAME>.admin.datocms.com"
} : {}
const response = await fetch(
  "https://graphql-staging.datocms.com/", 
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer <API-KEY>",
      ...visualEditingHeaders,
  },
  body: JSON.stringify({
    query, variables
  }),
});

How you declare the headers depends on the client you're using: please refer to your GraphQL/HTTP client documentation for more info.

Troubleshooting

Although, in general, your website should not break when you enable Visual Editing, there may be special situations that can cause problems.

Editable elements have the wrong style

In some cases (e.g. when using letter-spacing in CSS), the editable elements could have unexpected style. In those cases, you can use the functions available in the @vercel/stega library to extract the content and remove steganography data.

Install the library

npm i @vercel/stega

Then you can use a library helper like this:

import { vercelStegaSplit } from '@vercel/stega';
const { cleaned, encoded } = vercelStegaSplit(text);

Links appear for the wrong element

If the wrong element is highlighted when you enable visual editing, you can add the data-vercel-edit-target attribute to one of the parent elements:

<div class="card" data-vercel-edit-target>
  <h1>{editableTitle}</h1>
  <div>Some more text</div>
</div>

That way, even if the editable element is the <h1>, you will have the full card highlighted.

Inspecting visual editing data

Since the metadata added in the GraphQL response is encoded into invisible Unicode characters, it can be quite tricky to examine it.

Fortunately, when you enable the visual editing via the Vercel toolbar, a data-vercel-edit-info attribute is added to every element that contains steganography data: