Skip to main content

Bridge Mode

Bridge Mode overlays ClearCMS's visual editor on your custom frontend. Your frontend fetches content from the API and renders it; ClearCMS adds editing controls when an editor is logged in.

How it works​

  1. Your frontend renders the page using content from the ClearCMS API.
  2. You add bridge.js to your page.
  3. When a ClearCMS editor visits the page, bridge.js sends a BRIDGE_READY message to the ClearCMS editor frame.
  4. The editor activates bridge mode, overlaying edit controls based on data-clearcms-field attributes.
  5. Editors click fields to edit them inline, with complex fields opening in the right panel.

Bridge Mode is auto-detected. If bridge.js is present and BRIDGE_READY fires, the editor activates automatically.

Setup​

1. Add bridge.js​

Add the script to the <head> of your page:

<script src="https://your-site.clearcms.app/bridge.js" defer></script>

The script is small and has no effect on visitors not logged into ClearCMS.

2. Mark editable fields​

Add data-clearcms-field attributes to editable HTML elements:

<h1 data-clearcms-field="headline">We build great software</h1>
<p data-clearcms-field="subheadline">Based in London</p>

The attribute value must match the field name in your content schema.

3. Mark the content item​

Wrap editable fields in a container with data-clearcms-item and data-clearcms-type:

<article
  data-clearcms-item="post_001"
  data-clearcms-type="posts"
>
  <h1 data-clearcms-field="title">Hello World</h1>
  <div data-clearcms-field="body">
    <p>Post body content here.</p>
  </div>
</article>
AttributeValue
data-clearcms-itemThe content item's ID from the API
data-clearcms-typeThe content type slug (e.g. posts, team)
data-clearcms-fieldThe field name within that content item

Field types​

Different field types get different editing controls:

Field typeEditing behavior
Short textInline text editing directly in the element
Long text / rich textOpens a text editor in the right panel
ImageClick to open media picker
URL / linkEdits in right panel
Array / collectionClick item to edit in right panel
Boolean / selectEdits in right panel

Page-level fields​

For fields that belong to a page rather than a content item, use data-clearcms-page instead:

<section
  data-clearcms-page="{page-id}"
  data-clearcms-section="hero"
>
  <h1 data-clearcms-field="headline">Welcome</h1>
</section>

Detecting bridge mode in your frontend​

To conditionally render UI when the editor is active, listen for the clearcms:ready event:

window.addEventListener('clearcms:ready', (event) => {
  console.log('ClearCMS editor is active', event.detail);
  // e.g. show an "exit preview" button
});

Security​

bridge.js only activates when a valid ClearCMS session is present. Visitors without a session see your page as normal -- no editing UI, no extra network requests beyond the initial script load.

The script uses postMessage with origin validation. Only messages from *.clearcms.app are accepted.

Example: Next.js page​

// app/blog/[slug]/page.tsx
import { notFound } from 'next/navigation';

async function getPost(slug: string) {
  const res = await fetch(
    `https://your-site.clearcms.app/api/v1/content/posts/${slug}`,
    { next: { revalidate: 60 } }
  );
  if (!res.ok) return null;
  return res.json();
}

export default async function BlogPost({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await getPost(slug);
  if (!post) notFound();

  return (
    <>
      <script src="https://your-site.clearcms.app/bridge.js" defer />
      <article
        data-clearcms-item={post.id}
        data-clearcms-type="posts"
      >
        <h1 data-clearcms-field="title">{post.data.title}</h1>
        <div
          data-clearcms-field="body"
          dangerouslySetInnerHTML={{ __html: post.data.body }}
        />
      </article>
    </>
  );
}

Troubleshooting​

Editing controls don't appear

  • Confirm you are logged into ClearCMS in the same browser.
  • Check the browser console for BRIDGE_READY being sent.
  • Verify the data-clearcms-item ID matches the actual content item ID returned by the API.

Fields are not editable

  • Check the data-clearcms-field value matches the exact field name in the content schema.
  • Fields not defined in the schema are ignored by the editor.

Changes don't appear after saving

  • Your frontend may be caching API responses. If using ISR (Next.js) or similar, trigger revalidation on content updates. ClearCMS sends a webhook on publish -- see Settings > Developer > Webhooks.
Was this page helpful?