Vercel Visual Editing > How to use 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:

    With Visual Editing enabled, you can efficiently navigate to specific content without needing to know its exact location within DatoCMS.
    Vercel and DatoCMS requirements

    Right now, Vercel Visual Editing is in beta for Pro and Enterprise Vercel customers, while it's currently available for Enterprise DatoCMS customers. If you want to have the feature enabled in your DatoCMS projects, contact us at

    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 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

    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>"
    } : {}
    const response = await fetch(
    method: "POST",
    headers: {
    "Authorization": "Bearer <API-KEY>",
    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.


    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>
    <div>Some more text</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: