@handlewithcare/react-prosemirror

To create custom node views using React components, pass your components to the nodeViewComponents prop of the ProseMirror component.

Requirements for Node View Components:

1. Ref Forwarding: Components must pass their ref to their top-level DOM element.
2. Content DOM: Components that render children must pass nodeProps.contentDOMRef to the parent element of those children.
3. Props: Components receive NodeViewComponentProps, which includes nodeProps (containing node, getPos, decorations, and contentDOMRef).

Node View Hooks:

• useNodePos(): Returns the current position of the node. Note: Only use this in callbacks or effects; using it in render will not trigger re-renders on position changes.
• useIsNodeSelected(): Returns true if the node is currently selected.
• useIsComposingIn(): Returns true if an IME composition is active inside the node.
• useStopEvent(handler): Registers a stopEvent handler.
• useIgnoreMutation(handler): Registers an ignoreMutation handler.
• useSelectNode(selectNode, deselectNode): Registers selection handlers.

Because the EditorView relies on the DOM, accessing its methods (like coordsAtPos) during the React render cycle can lead to out-of-sync data. To safely interact with the EditorView from children of the <ProseMirror /> component, use these hooks:

• useEditorEffect: Use this for side effects that depend on the DOM being in sync with the latest EditorState, such as positioning a floating widget relative to the user's cursor.
• useEditorEventCallback: Use this to create stable function references for event handlers (like onClick) that need to access the EditorView to dispatch transactions.
• useEditorEventListener: Use this if you need to listen to events originating inside the contenteditable element (e.g., keydown). These listeners are registered via ProseMirror's handleDOMEvents. Returning true or calling event.preventDefault() prevents other listeners from running.

// Example: Using useEditorEffect to position a widget
useEditorEffect((view) => {
  if (!view || !ref.current) return;
  const viewClientRect = view.dom.getBoundingClientRect();
  const coords = view.coordsAtPos(view.state.selection.anchor);
  ref.current.style.top = coords.top - viewClientRect.top;
  ref.current.style.left = coords.left - viewClientRect.left;
});

v3 simplifies how CSS classes and element attributes are passed to the editor. Redundant ways to set className have been removed.

New Prop Locations:

1. attributes.class on ProseMirror: Use this to set classes on the editor container.
2. className on ProseMirrorDoc: Use this to set classes on the document content element.

Changes to as prop: In v2, as accepted a JSX element (e.g., <article data-editor />). In v3, as accepts a component or an element type string (e.g., "article" or Article). Any additional props passed to the element in the as prop should now be passed directly to ProseMirrorDoc or via attributes on ProseMirror.

function Editor() {
  return (
    <ProseMirror
      defaultState={EditorState.create({ schema, plugins: [reactKeys()] })}
    >
      {/* v3: Use 'as' for type and 'className'/'props' for attributes */}
      <ProseMirrorDoc as="article" className="editor" data-editor />
    </ProseMirror>
  );
}

In v3, the library no longer automatically detects contentDOM. Instead, it provides a contentDOMRef via nodeProps. If your node view component renders children, you must explicitly assign nodeProps.contentDOMRef to the parent element of those children.

If your node view consists of a single element where the ref (the node's DOM element) and the contentDOM are the same, use the useMergedDOMRefs utility hook to combine them.

import { useMergedDOMRefs } from "@handlewithcare/react-prosemirror";

// For components with a single element (merging ref and contentDOM)
function Paragraph({
  nodeProps,
  ref,
  children,
  ...props
}: NodeViewComponentProps) {
  return (
    <p ref={useMergedDOMRefs(ref, nodeProps.contentDOMRef)} {...props}>
      {children}
    </p>
  );
}

// For components with nested children (explicitly assigning contentDOMRef)
function Card({ nodeProps, ref, children, ...props }: NodeViewComponentProps) {
  return (
    <div ref={ref} {...props}>
      <div ref={nodeProps.contentDOMRef}>{children}</div>
    </div>
  );
}

To avoid issues with state tearing, asynchronous rendering causing extra DOM nodes, and broken React context in portals, replace @tiptap/react with the React ProseMirror integration layer. This allows you to keep your existing Tiptap extensions and commands while using a safer React-based rendering system that doesn't require wrapping DOM nodes.

Follow these steps to migrate:

1. Replace useEditor with useTiptapEditor.
2. Wrap EditorContent with TiptapEditorView and use TiptapEditorContent instead.
3. Replace useEffect and useCallback that depend on the editor with useTiptapEditorEffect and useTiptapEditorEventCallback.
4. Migrate custom node views using the tiptapNodeView HOC.

// 1. Replace useEditor
import { useTiptapEditor } from "@handlewithcare/react-prosemirror/tiptap";
const editor = useTiptapEditor({ extensions });

// 2. Replace EditorContent
import {
  TiptapEditorView,
  TiptapEditorContent,
  useTiptapEditor,
} from "@handlewithcare/react-prosemirror/tiptap";

export function Editor() {
  const editor = useTiptapEditor({ extensions });
  return (
    <TiptapEditorView editor={editor}>
      <TiptapEditorContent editor={editor} />
    </TiptapEditorView>
  );
}

// 3. Replace useEffect/useCallback
import { useTiptapEditorEffect, useTiptapEditorEventCallback } from "@handlewithcare/react-prosemirror/tiptap";

useTiptapEditorEffect((editor) => {
  editor.commands.focus();
}, [editor]);

const onClick = useTiptapEditorEventCallback((editor) => {
  editor.commands.focus();
});

// 4. Migrate Node Views
import { tiptapNodeView } from "@handlewithcare/react-prosemirror/tiptap";
import { Node } from "@tiptap/core";
import Paragraph from "./ParagraphView.jsx";

const extension = Node.create({ name: "paragraph" });
export const paragraph = tiptapNodeView({
  extension,
  component: Paragraph,
});

// Register in Editor
const nodeViewComponents = { paragraph };
<TiptapEditorView editor={editor} nodeViewComponents={nodeViewComponents}>
  <TiptapEditorContent editor={editor} />
</TiptapEditorView>"}],

Install the library along with its required peer dependencies.

Important Compatibility Notes:

1. ProseMirror View: Releases are coupled to specific prosemirror-view versions. Ensure your prosemirror-view version matches the one specified in the peer dependencies.
2. React Reconciler: You must ensure your react-reconciler version matches your react and react-dom versions.

React/Reconciler Compatibility Matrix:

CSS Requirement: You must import the prosemirror-view stylesheet for the editor to render correctly.

npm install @handlewithcare/react-prosemirror \
    react@^19.1.0 \
    react-dom@^19.1.0 \
    react-reconciler@0.32.0 \
    prosemirror-view@1.42.0 \
    prosemirror-state \
    prosemirror-model

// Import the required stylesheet
import "prosemirror-view/style/prosemirror.css";

You can use React components as ProseMirror node views by passing a nodeViewComponents object to the <ProseMirror /> component.

Requirements for Node View Components:

1. Stable Reference: Define nodeViewComponents outside of your main editor component (or memoize it with useMemo) to prevent unnecessary re-renders.
2. Refs: All node view components must pass a ref to their top-level DOM element. If using React <=18, use forwardRef to access the ref prop.
3. Content DOM: Components that render children must pass nodeProps.contentDOMRef to the element that wraps the children. If the top-level element is also the content container, use useMergedDOMRefs(ref, nodeProps.contentDOMRef).
4. Props Spreading: Spread all received props onto the top-level DOM element to ensure ProseMirror Decorations (attributes) are applied correctly.

Complex Layouts: If your top-level element is a wrapper (e.g., a div containing a p), use the ref for the wrapper and nodeProps.contentDOMRef for the inner element.

// Example: A simple Paragraph node view
function Paragraph({ children, nodeProps, ref, ...props }) {
  return (
    <p
      {...props}
      ref={useMergedDOMRefs(ref, nodeProps.contentDOMRef)}
    >
      {children}
    </p>
  );
}

const nodeViewComponents = {
  paragraph: Paragraph,
};

// Usage
<ProseMirror nodeViewComponents={nodeViewComponents} ... />