GrapesJS in React: an editor component that survives StrictMode

What you are building

A GrapesEditor React component, tested on React 19.1.1, that you can drop into an application. It mounts the GrapesJS editor into a div, hands the editor instance to the parent once it is ready, reports every change, and destroys the editor when the component unmounts.

The design decision that shapes everything below: GrapesJS is not a React component and does not want to be one. It creates an iframe canvas, renders HTML into it, and keeps its own model of the page. React's job is to give it a DOM node and get out of the way. If you want the opposite model, where your own React components are the editable units, read GrapesJS vs Puck before going further, and the React embedding use case for the wider choice.

Install

npm install grapesjs@0.23.5

React is assumed to be in the project already. The example runs on React 19.1.1.

The component

import { useEffect, useRef } from 'react';
import grapesjs, { type Editor, type ProjectData } from 'grapesjs';
import 'grapesjs/dist/css/grapes.min.css';

export type GrapesEditorProps = {
  /** Read once, on mount. Changing it later does not reload the editor. */
  initialProject: ProjectData;
  onReady?: (editor: Editor) => void;
  onChange?: (project: ProjectData) => void;
};

export function GrapesEditor({ initialProject, onReady, onChange }: GrapesEditorProps) {
  const containerRef = useRef<HTMLDivElement>(null);

  // Keep the latest callbacks without re-running the mount effect when a parent re-renders.
  const callbacks = useRef({ onReady, onChange });
  useEffect(() => {
    callbacks.current = { onReady, onChange };
  }, [onReady, onChange]);

  useEffect(() => {
    const container = containerRef.current;
    if (!container) return;

    const editor = grapesjs.init({
      container,
      height: '100%',
      storageManager: false,
      projectData: initialProject,
    });

    const handleUpdate = () => callbacks.current.onChange?.(editor.getProjectData());
    editor.on('update', handleUpdate);
    editor.onReady(() => callbacks.current.onReady?.(editor));

    return () => {
      editor.off('update', handleUpdate);
      editor.destroy();
    };
    // The editor owns its DOM: mount once, tear down on unmount.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, []);

  return <div ref={containerRef} style={{ height: '100%' }} />;
}

Four things in there are deliberate:

• The mount effect has an empty dependency list. initialProject is read once. Re-running the effect when a prop changes would destroy and recreate the editor, losing undo history and selection. To load a different project into a live editor, call editor.loadProjectData().
• Callbacks live in a ref. Parents usually pass inline functions, which change on every render. Reading them through callbacks.current keeps the latest version without re-mounting.
• Cleanup calls editor.destroy(). Without it, StrictMode's second mount creates a second editor inside the same container, and every unmount leaks the first one.
• storageManager: false. GrapesJS defaults to autosaving into localStorage. In an application you almost always want your own persistence, so turn the default off and choose deliberately.

Using it

import { StrictMode, useCallback, useRef, useState } from 'react';
import { createRoot } from 'react-dom/client';
import type { Editor, ProjectData } from 'grapesjs';
import { GrapesEditor } from './GrapesEditor';

const INITIAL_PROJECT: ProjectData = {
  pages: [{ component: '<section class="hero"><h1>Hello from React</h1></section>' }],
};

function App() {
  const editorRef = useRef<Editor | null>(null);
  const [changes, setChanges] = useState(0);
  const [saved, setSaved] = useState('');

  const handleReady = useCallback((editor: Editor) => {
    editorRef.current = editor;
  }, []);

  const handleChange = useCallback(() => setChanges((n) => n + 1), []);

  const handleAddSection = () => {
    editorRef.current?.addComponents('<section><p>Added from a React button</p></section>');
  };

  const handleSave = () => {
    const editor = editorRef.current;
    if (!editor) return;
    setSaved(JSON.stringify(editor.getProjectData()));
  };

  return (
    <div style={{ display: 'grid', gridTemplateRows: 'auto 1fr', height: '100vh' }}>
      <header style={{ display: 'flex', gap: 12, padding: 8 }}>
        <button type="button" onClick={handleAddSection}>
          Add section
        </button>
        <button type="button" onClick={handleSave}>
          Save
        </button>
        <span data-testid="changes">{changes}</span>
        <output data-testid="saved" hidden>
          {saved}
        </output>
      </header>
      <GrapesEditor initialProject={INITIAL_PROJECT} onReady={handleReady} onChange={handleChange} />
    </div>
  );
}

const root = document.getElementById('app');
if (!root) throw new Error('#app not found');
createRoot(root).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

The parent keeps the editor in a ref, not in state: the instance never changes after mount and nothing should re-render because of it. The "Add section" button shows the direction of control, React calls the editor API, and the update event carries changes back.

What our test checks

The example is bundled with esbuild in development mode, because StrictMode only double-mounts in development, then loaded in headless Chromium. The test asserts that:

1. exactly one .gjs-editor exists after StrictMode's mount, cleanup and remount;
2. the initial project renders inside the canvas iframe;
3. a React button that calls editor.addComponents() produces an update event that reaches React state;
4. getProjectData() returns JSON with one page containing the added section;
5. the browser logs no errors.

The script is scripts/verify-guide-examples.mjs in this site's repository and runs in CI on every change.

Two network requests you did not ask for

Font Awesome from cdnjs. The cssIcons option defaults to Font Awesome 4.7 on cdnjs.cloudflare.com, which the default panels use for icons. Our test saw this request on every load. If your Content Security Policy blocks third-party stylesheets, self-host the file and point cssIcons at it.

Telemetry. GrapesJS 0.23.5 posts the page's domain and the editor version to app.grapesjs.com once per browser session, skipping hostnames that contain "localhost". The GrapesJS documentation describes the data collected and the opt-out, which is telemetry: false in grapesjs.init().

Where this goes next

• Code-split the editor. We measured the GrapesJS core at 294.5 kB gzip in our bundle size benchmark. Put the editor on its own route and load it lazily; the Next.js guide shows one way.
• Persist projects. Saving and loading from a database replaces storageManager: false with a real backend.
• Give users something to drag. Custom blocks adds your own component types and blocks through a plugin.

What this guide does not cover

• Custom UI. The example keeps GrapesJS's default panels. Replacing them with React-rendered panels is a larger project and the main reason teams consider the Studio SDK.
• Rendering React components on the canvas. The canvas holds HTML. Wrapping React components as GrapesJS component types is possible but is not what this component does.
• Server rendering. The component initialises in an effect, so nothing renders on the server. See the Next.js guide for what that means in the App Router.
• @grapesjs/react. We did not test the official wrapper with 0.23.5; see the FAQ below.