DatoCMS Content Link

 

Click-to-edit overlays for DatoCMS projects. Platform and framework agnostic, two function calls to set it up.

``bash
npm install @datocms/content-link
`

!Usage demo

Quick start

$3

Make sure you pass the contentLink and baseEditingUrl options when initializing the DatoCMS CDA client:

`ts
import { executeQuery } from "@datocms/cda-client";

const result = await executeQuery(query, {
token: process.env.DATO_API_TOKEN,
contentLink: 'v1',
baseEditingUrl: 'https://acme.admin.datocms.com', // <- URL of your DatoCMS project (https://.admin.datocms.com)
});
`

$3

`ts
import { createController } from '@datocms/content-link';

const controller = createController();
controller.enableClickToEdit();
`

Note: You can also skip calling enableClickToEdit() and temporarily enable click-to-edit mode on-demand by holding down the Alt/Option key. The mode will be active while the key is held and automatically disable when released.

That's all you need for the majority of projects! If you see overlays and deep links opening the correct records, your setup is complete!

---

$3

`ts
import { createController } from '@datocms/content-link';

// Minimal (no options required)
const controller = createController();

// With options
const controller = createController({
// Optional: limit scanning/observation to this root instead of the whole document.
// Can be a ShadowRoot or a specific container element.
root: document.getElementById('preview-container'),

// Optional: strip stega-encoded invisible characters from text content (default: false)
stripStega: false
});

// Control click-to-edit overlays
controller.enableClickToEdit(); // turn click-to-edit overlays on
controller.enableClickToEdit({ // with visual flash highlighting all editable elements
scrollToNearestTarget: true // optionally scroll to nearest editable if none visible
});
controller.disableClickToEdit(); // turn click-to-edit overlays off
controller.isClickToEditEnabled(); // check if click-to-edit is currently enabled
controller.isDisposed(); // check if disposed
controller.dispose(); // permanently tear down and clean up (controller becomes inert)
`

Returns a controller to manage DOM stamping and click-to-edit overlays.

Options:
- root?: ParentNode: Limit scanning to a specific container (default: document)
- stripStega?: boolean: Whether to strip stega-encoded invisible characters from text content after stamping (default: false). Stega embeds invisible, zero-width UTF-8 characters into text content to encode editing metadata.
- When false (default): Stega encoding remains in the DOM, allowing controllers to be disposed and recreated on the same page. The invisible characters don't affect display but preserve the source of truth.
- When true: Stega encoding is permanently removed from text nodes, providing clean textContent for programmatic access. However, recreating a controller on the same page won't detect elements since the encoding is lost.

Controller methods:
- enableClickToEdit(flashAll?: { scrollToNearestTarget: boolean }): Turn click-to-edit overlays on (allows clicking elements to open the editor). Optionally pass flashAll to briefly highlight all editable elements with an animated effect, and scroll to the nearest one if none are visible.
- disableClickToEdit(): Turn click-to-edit overlays off (DOM stamping continues)
- isClickToEditEnabled(): Returns true if click-to-edit is currently enabled
- isDisposed(): Returns true if the controller has been disposed
- dispose(): Permanently disconnects observers and cleans up. After dispose, the controller cannot be re-enabled; create a new one if needed
- flashAll(scrollToNearestTarget?: boolean): Briefly highlight all editable elements with an animated effect. Optionally scroll to the nearest editable element if none are visible.

Keyboard shortcuts:
- Alt/Option key: Hold down to temporarily enable/disable click-to-edit mode. This toggles the current state and reverts when the key is released.

Note: DOM stamping (detecting and marking editable elements) runs automatically when the controller is created and continues until dispose() is called. Click-to-edit overlays are independent and must be explicitly enabled with enableClickToEdit().

---

Web Previews Plugin Integration

When your website runs inside the Visual Editing mode of the Web Previews plugin, the controller automatically establishes bidirectional communication with the plugin.

This connection is completely automatic and requires no configuration. If your preview is not running in an iframe or the connection fails, the library gracefully falls back to opening edit URLs in a new tab.

$3

If your website uses client-side routing (like Next.js, React Router, etc.), you need to set up bidirectional communication with the plugin:

`tsx
// Next.js App Router example
'use client';

import { createController } from '@datocms/content-link';
import { useRouter, usePathname } from 'next/navigation';
import { useEffect } from 'react';

export default function PreviewPage() {
const router = useRouter();
const pathname = usePathname();

useEffect(() => {
const controller = createController({
// Handle navigation requests from the plugin
onNavigateTo: (path) => {
router.push(path);
}
});

return () => controller.dispose();
}, [router]);

useEffect(() => {
// Notify the plugin when the URL changes
controller?.setCurrentPath(pathname);
}, [pathname]);

return ;
}
`

Available option:
- onNavigateTo?: (path: string) => void: Callback invoked when the Web Previews plugin requests navigation to a different URL

Available method:
- setCurrentPath(path: string): Notify the Web Previews plugin of the current URL

---

Advanced usage

$3

By default, the controller preserves stega-encoded invisible characters in the DOM. This allows you to safely dispose and recreate controllers on the same page without losing the ability to detect editable elements:

`ts
// Create initial controller
const controller1 = createController();
controller1.enableClickToEdit();

// Later, dispose it
controller1.dispose();

// Create a new controller - it will still find all editable elements
const controller2 = createController();
controller2.enableClickToEdit();
`

This is particularly useful for:
- Testing scenarios with setup/teardown
- Single Page Applications that need to recreate controllers during navigation
- Hot-reloading during development
- Any scenario requiring controller restart without page reload

If you need clean text content for programmatic access (without invisible stega characters), use stripStega: true. However, note that this permanently removes the stega encoding, preventing controller recreation:

`ts
const controller = createController({ stripStega: true });

// After disposal, creating a new controller won't find elements
controller.dispose();
const controller2 = createController(); // Won't detect editable elements
`

$3

You can show users where all the editable elements are on the page in two ways:

1. When enabling click-to-edit mode:
`ts
controller.enableClickToEdit({
scrollToNearestTarget: true
});
`

2. As a standalone method:
`ts
// Highlight all editable elements
controller.flashAll();

// Highlight and scroll to nearest editable if none visible
controller.flashAll(true);
`

This will:
1. Briefly highlight all editable elements with an animated fade-in/out effect (using a staggered animation)
2. If scrollToNearestTarget is true and no editable elements are currently visible in the viewport, automatically scroll to the nearest editable element

This is particularly useful for:
- Onboarding users to the editing experience
- Helping editors quickly identify what content they can edit
- Navigating to editable content on long pages

$3

This library uses several data-datocms-* attributes. Some are developer-specified (you add them to your markup), and some are library-managed (added automatically during DOM stamping). Here's a complete reference.

#### Developer-specified attributes

These attributes are added by you in your templates/components to control how editable regions behave.

##### data-datocms-content-link-url

Manually marks an element as editable with an explicit edit URL. Use this for non-text fields (booleans, numbers, dates, JSON) that cannot contain stega encoding. The recommended approach is to use the _editingUrl field available on all records:

`graphql
query {
product {
id
price
isActive
_editingUrl
}
}
`

`tsx

${product.price}

`

##### data-datocms-content-link-source

Attaches stega-encoded metadata without the need to render it as content. Useful for structural elements that cannot contain text (like