Visual Editing

Visual Editing lets content editors click directly on any element of your website to edit it in DatoCMS, without hunting through forms and fields. Combined with draft content and real-time updates, editors see changes reflected instantly on the page as they type.

The problem it solves

In a traditional headless CMS workflow, there's a disconnect between what editors see in the CMS (forms, fields, JSON) and what visitors see on the website. Editors have to make changes in the CMS, save, wait for a preview to rebuild, switch tabs to check the result, and go back to make further adjustments. This loop is slow, error-prone, and frustrating — especially for non-technical editors who think in terms of "the headline on the homepage", not "the title field on the home_page record".

Visual Editing closes this gap entirely. Editors work with the actual website (the real layout, the real typography, the real context) and every piece of content becomes a direct entry point back into the CMS.

Two ways to use it

Visual Editing supports two workflows that serve different editing styles. Both can coexist, and editors pick whichever suits the task at hand.

Browsing the website directly

Editors visit the website in draft mode (typically via a preview URL) and interact with content right there. When they hover over any editable element (a title, body text, an image alt text) a subtle overlay appears. Clicking it opens DatoCMS in a new browser tab, navigated directly to the exact field that controls that piece of content. There's no guesswork about "where does this text live in the CMS?".

Side-by-side editing inside DatoCMS

The Web Previews plugin is the bridge that connects your website to your DatoCMS project. Once installed, it brings a live preview of your website directly into the DatoCMS interface, turning the CMS from a form-based tool into a visual editing environment.

The plugin adds several touchpoints to the DatoCMS UI:

• A "Visual" tab in the main navigation: a full-screen, side-by-side editing view where the website preview sits next to the editing panel. Editors click on any element in the preview, and the corresponding record and field open right there. The tab includes:

  • An address bar for navigating the preview

  • Viewport controls for testing responsive layouts

  • A frontend selector for switching between environments (e.g. production vs. staging)

• Preview links in the record sidebar: when editors open any record, they see quick links to view that content on the actual website. The plugin determines which URL corresponds to each record by calling an API endpoint on your frontend.

• A full iframe preview in the sidebar: beyond just links, editors can expand an inline preview of the page directly in the sidebar, with viewport presets (mobile, tablet, desktop) and auto-reload on save.

The plugin supports multiple frontends, so if your content powers different websites or environments, editors can switch between them from a single dropdown.

Bidirectional navigation

The connection between the CMS and the preview works in both directions. When editors browse through records in DatoCMS, the preview navigates to the corresponding page automatically. And when they click around in the website preview, DatoCMS follows along, opening the relevant record. This means editors can start from whichever side feels natural (the content or the page) and the other side stays in sync.

Real-time feedback

In both workflows, when combined with Real-time Updates, editors see their changes reflected on the preview as they type. There's no need to reload: the preview updates live, giving editors immediate confidence that their changes look right in context.

The building blocks

Visual Editing is not a single feature, but the combination of several DatoCMS capabilities that can be adopted incrementally:

• Draft Mode: lets your frontend serve unpublished content during preview sessions

• Real-time Updates: pushes content changes to the preview without a page refresh

• Content Link: adds click-to-edit overlays connecting frontend elements to CMS fields

• Web Previews plugin: embeds the preview inside DatoCMS for a unified editing experience

You can adopt each capability independently and stop at any point — each one delivers value on its own. But the full combination is where the experience really comes together.

The integration of all these layers is designed to be straightforward, especially if you start from one of our tech starter kits. These official scaffolds come pre-configured with Draft Mode, Real-time Updates, Content Link, and Web Previews already wired together, so you get a fully working Visual Editing setup with minimal effort and can focus on your content and design.

How it works technically

1. Embedded metadata

When your frontend fetches draft content from the Content Delivery API, DatoCMS can embed invisible metadata into text fields. This metadata, hidden using special Unicode characters that don't affect how text appears visually, carries information about which record and field produced each piece of text.

You enable this by passing two options when querying:

executeQuery(query, {
  includeDrafts: true,
  contentLink: 'v1',
  baseEditingUrl: 'https://your-project.admin.datocms.com',
});

2. Content Link component

A <ContentLink /> component (available for every supported framework) scans the page for this embedded metadata and renders interactive overlays on hover. Clicking an overlay opens DatoCMS at the exact field — either in a new tab or inside the Web Previews plugin panel if the site is loaded within DatoCMS. The component detects its context automatically, so no code changes are needed on your frontend to support both modes.

You render this component in your root layout, only when draft mode is active:

{draftModeEnabled && <ContentLink />}

3. Web Previews plugin

The Web Previews plugin communicates with your frontend through two integration points:

• Preview Links API: an endpoint on your frontend that receives record information from DatoCMS (the record ID, model API key, and current locale) and returns the URL where that record can be previewed. This is how the plugin knows which page to show for each record.

• Draft Mode route: your existing route that activates draft mode and redirects to the preview page. The plugin calls this to ensure the iframe always loads draft content.

The Content Link component on your frontend and the plugin communicate automatically via an iframe messaging protocol: when an editor clicks on content in the preview, the frontend tells the plugin which record to open, and the plugin navigates the CMS accordingly.

Setting up the plugin

1. Install the Web Previews plugin from the DatoCMS marketplace

2. Add a frontend with:

   • Name: a label for this frontend (e.g. "Production", "Staging")

   • Preview Links API endpoint: https://yoursite.com/api/preview-links?token=your-secret

   • Draft Mode route: https://yoursite.com/api/draft-mode/enable?token=your-secret

3. Optionally configure custom viewport presets, multiple frontends, and sidebar display preferences

Framework integration guides

Each framework has its own guide covering the full setup (Draft Mode, Real-time Updates, Content Link, and Web Previews) with working code from our official starter kits:

• Next.js Visual Editing

• Nuxt Visual Editing

• SvelteKit Visual Editing

• Astro Visual Editing

Underlying library

All framework integrations are built on top of @datocms/content-link, a framework-agnostic library that handles metadata detection, overlay rendering, and communication with the Web Previews plugin. If you're using a framework we don't have an SDK for, you can integrate directly with this library.

Comparison with Vercel Content Link

Vercel offers a similar feature also called Content Link (part of Vercel's Edit Mode). DatoCMS fully integrates with Vercel Content Link — the Content Delivery API can embed the metadata that Vercel expects, so you can use Vercel's overlay UI if you prefer. We have a dedicated guide for setting up Vercel Content Link with DatoCMS.

Both approaches use the same underlying technique (invisible metadata embedded in text fields), but there are key differences:

• Plan requirements: Vercel Content Link requires a Vercel Pro or Enterprise plan. DatoCMS Visual Editing works on every plan, including Free.

• Environment: Vercel Content Link only works on Vercel preview deployments. DatoCMS Visual Editing works in any environment (development, staging, or production) and on any hosting platform.

• Editing experience: Vercel Content Link opens the CMS in a new tab. DatoCMS Visual Editing (with the Web Previews plugin) offers a side-by-side editing experience directly within DatoCMS, with bidirectional navigation and real-time updates.