Building a Sleek RTE in GrapesJS using ProseMirror

If you have ever tried embedding a modern rich text editor into GrapesJS, you have almost certainly looked at TipTap. On paper, it sounds like the ideal pairing: TipTap provides a sleek and functional RTE right out the gate. In practice, integrating TipTap into GrapesJS is notoriously frustrating.

There is a significantly cleaner architecture: bypass TipTap's application shell, drop straight to ProseMirror as the model layer via grapesjs-prosemirror, and construct a native, floating bubble toolbar using shadcn/ui and grapesjs-react.

Why ProseMirror works better than TipTap:

1. The Clashing Editor Problem (TipTap vs. GrapesJS)

TipTap is not just an editing engine; it is designed as an all-in-one, standalone application layer built to manage document lifecycles.

TipTap expects to own the editor's mount node, event delegation, focus transitions, and document serialization.
GrapesJS also manages DOM nodes inside its iframe canvas, handles element selection, binds drag-and-drop listeners, and triggers component-level lifecycle updates.

When you initialize TipTap inside a GrapesJS canvas text component, these runtimes immediately clash. You run into focus stealing, broken undo/redo histories, destroyed cursor selections on canvas clicks, and broken styling.

2. ProseMirror: The Foundation

TipTap is fundamentally a wrapper around ProseMirror.

ProseMirror does not try to be opinionated. It is a toolkit for building rich text editors based on functional state management:

EditorState: An immutable data structure representing the document, selection, and schema.
Transaction: Explicit changes applied to the state (similar to Redux or Git commits).
EditorView: A lightweight layer that translates the state into the DOM and catches user interactions.

Because ProseMirror acts strictly as a headless model layer, it does not battle GrapesJS for DOM control. It can be mounted, updated, and dismantled on demand without hijacking canvas events.

3. The Role of grapesjs-prosemirror

Instead of manually wiring up ProseMirror schemas, transactions, serializer round-trips, and GrapesJS's setCustomRte() hook, grapesjs-prosemirror handles the plumbing:

Hooks cleanly into GrapesJS’s text component edit lifecycle (double-click to activate, blur to sync).
Manages the ProseMirror instance creation, cleanup and HTML serialization.
Exposes a pluggable UIAdapter lifecycle (mount, update, destroy), passing the active view, state, and toolbar container element so you can render whatever React interface you want.

Building the RTE

We will be focusing solely on the RTE creation and not around the setup of the project itself, you can start from any of the examples provided for grapesjs-react, or implement in an existing project.

Part 1: Building the UI Adapter

ProseMirror runs on an imperative transaction loop, while React relies on declarative rendering. To connect them without unnecessary full-tree re-renders, use an event bus inside a custom UIAdapter.

Whenever ProseMirror dispatches a transaction (e.g., cursor moves or marks change), grapesjs-prosemirror calls update(), triggering our lightweight bus to re-render the toolbar.

react-ui-adapter.tsx

// react-ui-adapter.tsx
import { createRoot, type Root } from "react-dom/client";
import { useEffect, useReducer } from "react";
import type { UIAdapter, UIContext, UIInstance } from "@workspace/grapesjs-prosemirror";
import { RTEToolbar } from "./rte-toolbar";

export function createRerenderBus() {
  const listeners = new Set<() => void>();
  return {
    subscribe(fn: () => void) {
      listeners.add(fn);
      return () => listeners.delete(fn);
    },
    emit() {
      for (const fn of listeners) fn();
    },
  };
}

export function useRerender(bus: ReturnType<typeof createRerenderBus>) {
  const [, force] = useReducer((x) => x + 1, 0);
  useEffect(() => {
    return bus.subscribe(force);
  }, [bus]);
}

export function createReactUIAdapter(): UIAdapter {
  return {
    mount(ctx: UIContext): UIInstance {
      const { toolbarEl } = ctx;
      toolbarEl.innerHTML = "";

      const host = document.createElement("div");
      toolbarEl.appendChild(host);

      const bus = createRerenderBus();
      let root: Root | null = createRoot(host);

      root.render(<RTEToolbar ctx={ctx} bus={bus} />);

      return {
        update() {
          bus.emit();
        },
        destroy() {
          root?.unmount();
          root = null;
          host.remove();
        },
      };
    },
  };
}

Preventing the default mouse-down behavior is essential in any rich text editor so clicking the toolbar does not steal focus or blur the canvas text selection. Let's add a ToolbarButton

primitive.

toolbar-button.tsx

// toolbar-button.tsx
import * as React from "react";
import { Button } from "@workspace/ui/components/button";
import { cn } from "@workspace/ui/lib/utils";

export function ToolbarButton({
  children,
  active,
  className,
  ...props
}: React.ButtonHTMLAttributes<HTMLButtonElement> & { active?: boolean }) {
  return (
    <Button
      type="button"
      variant={active ? "default" : "ghost"}
      size="icon"
      className={cn("h-6 w-6", className)}
      {...props}
    >
      {children}
    </Button>
  );
}

To build mark controls cleanly, isolate the button primitive with shadcn and rely on the command utilities provided by @workspace/grapesjs-prosemirror:

markIsActive(schema, state, markName): Reads the current cursor or selection state to determine if the mark is applied.
run(view, markType): Toggles the mark in the ProseMirror transaction pipeline.

rte-toolbar.tsx

// rte-toolbar.tsx
import React from "react";
import { Bold, Italic, Underline, Strikethrough } from "lucide-react";
import {
  type UIContext,
  markIsActive,
  run,
} from "@workspace/grapesjs-prosemirror";
import { ToolbarButton } from "./toolbar-button";
import { useRerender, type createRerenderBus } from "./react-ui-adapter";

export function RTEToolbar({
  ctx,
  bus,
}: {
  ctx: UIContext;
  bus: ReturnType<typeof createRerenderBus>;
}) {
  useRerender(bus);

  const view = ctx.rte.view;
  const schema = view.state.schema;

  // 1. Read active mark states via grapesjs-prosemirror utils
  const bold = markIsActive(schema, view.state, "strong");
  const italic = markIsActive(schema, view.state, "em");
  const underline = markIsActive(schema, view.state, "underline");
  const strikethrough = markIsActive(schema, view.state, "strike");

  // 2. Helper to execute commands while preserving focus
  function onToggleCommand(
    e: React.MouseEvent<HTMLElement, MouseEvent>,
    cmd: () => void,
  ) {
    e.preventDefault();
    e.stopPropagation();
    cmd();
    view.focus();
  }

  return (
    <div className="flex items-center gap-1 rounded-lg border bg-secondary p-0.5">
      <ToolbarButton
        active={bold}
        onClick={(e) => onToggleCommand(e, () => run(view, schema.marks.strong!))}
        title="Bold"
      >
        <Bold className="h-3 w-3" />
      </ToolbarButton>

      <ToolbarButton
        active={italic}
        onClick={(e) => onToggleCommand(e, () => run(view, schema.marks.em!))}
        title="Italic"
      >
        <Italic className="h-3 w-3" />
      </ToolbarButton>

      <ToolbarButton
        active={underline}
        onClick={(e) => onToggleCommand(e, () => run(view, schema.marks.underline!))}
        title="Underline"
      >
        <Underline className="h-3 w-3" />
      </ToolbarButton>

      <ToolbarButton
        active={strikethrough}
        onClick={(e) => onToggleCommand(e, () => run(view, schema.marks.strike!))}
        title="Strikethrough"
      >
        <Strikethrough className="h-3 w-3" />
      </ToolbarButton>
    </div>
  );
}

Beyond simple inline mark toggles, you will often need complex input components like numeric stepper selects.

Here is an example extension: a composite FontSizeInput that pairs shadcn's <Select> with increment/decrement steppers. Notice again that onMouseDown stops propagation to ensure GrapesJS does not cancel the active text selection while you adjust the font size.

font-size-input.tsx

// font-size-input.tsx
import { Button } from "@workspace/ui/components/button";
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@workspace/ui/components/select";
import { Minus, Plus } from "lucide-react";

export const FONT_SIZES = [10, 12, 14, 16, 18, 20, 24, 32, 48];

export function FontSizeInput({
  value,
  onChange,
  disabled,
}: {
  value: number;
  onChange?: (size: number) => void;
  disabled?: boolean;
}) {
  const handleDecrement = () => {
    if (value > 1) onChange?.(value - 1);
  };

  const handleIncrement = () => {
    if (value < 999) onChange?.(value + 1);
  };

  return (
    <div
      className="flex h-6 items-center rounded border bg-background"
      onMouseDown={(e) => {
        e.preventDefault();
        e.stopPropagation();
      }}
    >
      <Button
        type="button"
        variant="ghost"
        size="icon"
        onClick={handleDecrement}
        className="h-full w-6 rounded-none rounded-l"
        disabled={disabled}
      >
        <Minus className="h-3 w-3" />
      </Button>

      <Select
        value={String(value)}
        disabled={disabled}
        onValueChange={(v) => {
          const n = Number(v);
          if (Number.isFinite(n)) onChange?.(n);
        }}
      >
        <SelectTrigger
          className="!h-full w-12 border-none [&>svg]:hidden"
          onMouseDown={(e) => {
            e.preventDefault();
            e.stopPropagation();
          }}
        >
          <SelectValue>{value}</SelectValue>
        </SelectTrigger>

        <SelectContent
          className="min-w-0"
          onMouseDown={(e) => {
            e.preventDefault();
            e.stopPropagation();
          }}
        >
          {FONT_SIZES.map((size) => (
            <SelectItem key={size} value={String(size)}>
              {size}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>

      <Button
        type="button"
        variant="ghost"
        size="icon"
        onClick={handleIncrement}
        className="h-full w-6 rounded-none rounded-r"
        disabled={disabled}
      >
        <Plus className="h-3 w-3" />
      </Button>
    </div>
  );
}

To incorporate this into your toolbar, read the current size using getActiveFontSize(view) and apply updates via setFontSize(schema, view, value):

tsx

import { getActiveFontSize, setFontSize } from "@workspace/grapesjs-prosemirror";
import { FontSizeInput } from "./font-size-input";

// Inside RTEToolbar:
const fontSize = getActiveFontSize(view);

<FontSizeInput
  value={fontSize}
  onChange={(value) => setFontSize(schema, view, value)}
/>

There is a lot more utilities that come with grapesjs-prosemirror which we will not be covering, feel free to check out the plugin and reach out if you need help with any features or if there's any features currently missing that you would like to be includes.

Part 2: Registering the Plugin with GrapesJS

Once your UI adapter and components are in place, plug it directly into your GrapesJS editor initialization:

typescript

import { usePlugin as grapesjsPlugin } from "grapesjs";
import { prosemirror } from "grapesjs-prosemirror";
import { createReactUIAdapter } from "./react-ui-adapter";

const config = {
  // ... other config options
  plugins: [
    grapesjsPlugin(prosemirror, {
      ui: createReactUIAdapter(),
    }),
  ],
};

Jump-Start Your Implementation

Building a custom rich text editor interface, syncing reactive button states to transaction streams, and matching canvas overlay positions takes time to get right.

If you want to skip building the editor infrastructure from scratch, take a look at grapesjs-shadcn. It is a complete, production-ready GrapesJS preset built on @grapesjs/react, Tailwind CSS, and shadcn/ui. It includes this full ProseMirror integration right out of the box and it is the framework behind ComposeIt's editor. It is currently available with a massive discount, saving you weeks of wiring up canvas adapters and UI glue so you can focus directly on building your application.