Detect the Visual Editor and initialize

Custom integrations built with the Visual Editor API should only appear inside the Visual Editor, never on the live website.

In the Doodle Gallery example, the gallery of doodles appears as the first item on the webpage when you view it through your internet browser.

The drawing canvas only appears at the top of the webpage when loaded in the Visual Editor.

When you open a file in the Visual Editor, CloudCannon injects a script that sets window.inEditorMode to true in the document before loading it into the iframe, and leaves it undefined everywhere else. We can use this flag to keep custom integrations inside the Visual Editor. Once we know we're in the Visual Editor, we can request the API with window.CloudCannonAPI.useVersion('v1', true).

The Doodle Gallery imports the API's types from the @cloudcannon/visual-editor-api package. Because the types are only used at build time, install it as a dev dependency:

npm install --save-dev @cloudcannon/visual-editor-api

import { useState, useRef, useEffect } from 'react';
import type { CloudCannonVisualEditorAPIV1, CloudCannonVisualEditorWindow } from '@cloudcannon/visual-editor-api'; 

declare const window: CloudCannonVisualEditorWindow & { inEditorMode: true | undefined } 

export function Doodler() {
  const apiRef = useRef<CloudCannonVisualEditorAPIV1 | undefined>(undefined); 
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const [inCloudCannonEditor, setInCloudCannonEditor] = useState<boolean>(false);

  useEffect(() => {
    if (!window.inEditorMode) { 
      return;
    }
    setInCloudCannonEditor(true);

    const initApi = () => {
      apiRef.current = window.CloudCannonAPI?.useVersion('v1', true); 
    };

    if (window.CloudCannonAPI) { 
      initApi();
      return;
    }

    document.addEventListener('cloudcannon:load', initApi, { once: true }); 
    return () => document.removeEventListener('cloudcannon:load', initApi);
  }, []);

  if (!inCloudCannonEditor) {
    return undefined; 
  }

  // ...render the drawing tool
}

The Visual Editor API is available on window.CloudCannonAPI whenever a file is open in the Visual Editor. The Doodle Gallery initializes it inside a React useEffect, but the same approach works in any framework — the only requirement is that the code runs in the browser, not during a server-side build.

Depending on how your integration loads, window.CloudCannonAPI may not exist yet when your code first runs.

Before the Doodle Gallery integration performs any other actions, it checks whether the webpage is already running in the Visual Editor, then initializes the Visual Editor API. If not, it waits for the cloudcannon:load event, which CloudCannon dispatches after setting window.CloudCannonAPI. Because the API Object lives in a useRef, it's ready whenever a Team Member later submits a doodle, no matter which path initialized it.

In the next step of this guide, we'll render the custom interface Team Members use to draw a doodle.