React ProseMirror

A fully featured library for safely integrating ProseMirror and React.

The state of this library

@nytimes/react-prosemirror just published its first stable release, v1.0.0. The code for that version of the library lives on the v1.x branch, and users of that version should view the README.md on that branch for relevant documentation.

Moving forward, the main branch of this library will focus on the upcoming v2 release, previously the react-editor-view branch. This entails a significant re-write of the underlying EditorView integration, and will include some breaking API changes.

To try out the new version, install @nytimes/react-prosemirror@next. We'd love to hear your thoughts!

Installation

npm:

npm install @nytimes/react-prosemirror

yarn:

yarn add @nytimes/react-prosemirror

• The Problem
• The Solution
  • Rendering ProseMirror Views within React
    • useEditorEffect
    • useEditorEventCallback
    • useEditorEventListener
  • Building node views with React
• What's changing in v2?
  • API changes
• API
  • ProseMirror
  • ProseMirrorDoc
  • useEditorState
  • useEditorEventCallback
  • useEditorEventListener
  • useEditorEffect
  • NodeViewComponentProps
  • useStopEvent
  • useSelectNode
  • widget

The Problem

To make updates efficient, React separates updates into phases so that it can process updates in batches. In the first phase, application code renders a virtual document. In the second phase, the React DOM renderer finalizes the update by reconciling the real document with the virtual document.

On the other hand, the ProseMirror View library renders ProseMirror documents in a single-phase update. Unlike React, it also allows built-in editing features of the browser to modify the document under some circumstances, deriving state updates from view updates rather than the other way around.

It is possible to use both React DOM and ProseMirror View, but using React DOM to render ProseMirror View components safely requires careful consideration of differences between the rendering approaches taken by each framework. The first phase of a React update should be free of side effects, which requires that updates to the ProseMirror View happen in the second phase. This means that during the first phase, React components actually have access to a different (newer) version of the EditorState than the one in the Editorview. As a result code that dispatches transactions may dispatch transactions based on incorrect state. Code that invokes methods of the ProseMirror view may make bad assumptions about its state that cause incorrect behavior or errors.

It's also challenging to effectively use React to define node views for ProseMirror documents. Both ProseMirror and React expect to have full control over their respective parts of the DOM. They both modify and destroy DOM nodes as needed. Previous solutions (including previous iterations of this library) have attempted to work around this power struggle by producing wrapper elements to hand to ProseMirror, and then mounting React nodes within these (usually with React Portals).

This approach works, but tenuously. Having additional nodes in the document that ProseMirror isn't strictly aware of can cause issues with its change detection system, leading to challenging edge cases. Here's an example. These extra wrapping elements also make it challenging to produce semantic markup and introduce challenges when styling.

The Solution

This library provides an alternate implementation of ProseMirror's EditorView. It uses React as the rendering engine, rather than ProseMirror's home-brewed DOM update system. This allows us to provide a more comfortable integration with ProseMirror's powerful data model, transformations, and event management systems.

Rendering ProseMirror Views within React

This library provides a set of React contexts and hooks for consuming them that ensure safe access to the EditorView from React components. This allows us to build React applications that contain ProseMirror Views, even when the EditorState is lifted into React state, or a global state management system like Redux.

The simplest way to make use of these contexts is with the <ProseMirror /> component. The <ProseMirror /> component can be used controlled (via the state prop) or uncontrolled (via the defaultState prop).

import { EditorState } from "prosemirror-state";
import {
  ProseMirror,
  ProseMirrorDoc,
  reactKeys,
} from "@nytimes/react-prosemirror";

export function ProseMirrorEditor() {
  return (
    <ProseMirror
      defaultState={EditorState.create({
        schema,
        plugins: [
          // The reactKeys plugin is required for the ProseMirror component to work!
          reactKeys(),
        ],
      })}
    >
      <ProseMirrorDoc />
    </ProseMirror>
  );
}

The EditorState can also easily be lifted out of the ProseMirror component and passed as a prop.

import { EditorState } from "prosemirror-state";
import { schema } from "prosemirror-schema-basic";
import {
  ProseMirror,
  ProseMirrorDoc,
  reactKeys,
} from "@nytimes/react-prosemirror";

export function ProseMirrorEditor() {
  const [editorState, setEditorState] = useState(
    EditorState.create({ schema, plugins: [reactKeys()] })
  );

  return (
    <ProseMirror
      state={editorState}
      dispatchTransaction={(tr) => {
        setEditorState((s) => s.apply(tr));
      }}
    >
      <ProseMirrorDoc />
    </ProseMirror>
  );
}

The EditorView interface exposes several useful methods that provide access to the DOM or data derived from its layout, such as coordsFromPos. These methods should only be accessed outside of the render cycle, to ensure that the DOM has been updated to match the latest state. React ProseMirror provides two hooks to enable this access pattern: useEditorEffect and useEditorEventCallback. Both of these hooks can be used from any children of the ProseMirror component.

useEditorEffect

Often, it's necessary to position React components relative to specific positions in the ProseMirror document. For example, you might have some widget that needs to be positioned at the user's cursor. In order to ensure that this positioning happens when the DOM is in sync with the latest EditorState, we can use useEditorEffect.

// SelectionWidget.tsx
import { useRef } from "react";
import { useEditorEffect } from "@nytimes/react-prosemirror";

export function SelectionWidget() {
  const ref = useRef();

  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;
  })

  return (
    <div
      ref={ref}
      style={{
        position: "absolute"
      }}
    />
  );
}

// ProseMirrorEditor.tsx
import {
  ProseMirror,
  ProseMirrorDoc,
  reactKeys
} from '@nytimes/react-prosemirror';
import { EditorState } from "prosemirror-state";
import { schema } from "prosemirror-schema-basic";

import { SelectionWidget } from "./SelectionWidget.tsx";

export function ProseMirrorEditor() {
  const [editorState, setEditorState] = useState(
    EditorState.create({ schema, plugins: [reactKeys()] })
  );

  return (
    <ProseMirror
      state={editorState}
      dispatchTransaction={(tr) => {
        setEditorState(s => s.apply(tr))
      }}
    >
      <ProseMirrorDoc />
      {/*
        We have to mount all components that need to access the
        EditorView as children of the ProseMirror component
      */}
      <SelectionWidget />
    </ProseMirror>
  );
}

useEditorEventCallback

It's also often necessary to dispatch transactions or execute side effects in response to user actions, like mouse clicks and keyboard events. Note: if you need to respond to keyboard events from within the contenteditable element, you should instead use useEditorEventListener.

However, if you need to dispatch a transaction in response to some event dispatched from a React component, like a tooltip or a toolbar button, you can use useEditorEventCallback to create a stable function reference that can safely access the latest value of the EditorView.

// BoldButton.tsx
import { toggleMark } from "prosemirror-commands";
import { useEditorEventCallback } from "@nytimes/react-prosemirror";

export function BoldButton() {
  const onClick = useEditorEventCallback((view) => {
    if (!view) return;
    const toggleBoldMark = toggleMark(view.state.schema.marks.bold);
    toggleBoldMark(view.state, view.dispatch, view);
  });

  return <button onClick={onClick}>Bold</button>;
}

// ProseMirrorEditor.tsx
import {
  ProseMirror,
  ProseMirrorDoc,
  reactKeys,
} from "@nytimes/react-prosemirror";
import { EditorState } from "prosemirror-state";
import { schema } from "prosemirror-schema-basic";

import { BoldButton } from "./BoldButton.tsx";

export function ProseMirrorEditor() {
  const [editorState, setEditorState] = useState(
    EditorState.create({ schema, plugins: [reactKeys()] })
  );

  return (
    <ProseMirror
      state={editorState}
      dispatchTransaction={(tr) => {
        setEditorState((s) => s.apply(tr));
      }}
    >
      <ProseMirrorDoc />
      {/*
        We have to mount all components that need to access the
        EditorView as children of the ProseMirror component
      */}
      <BoldButton />
    </ProseMirror>
  );
}

useEditorEventListener

useEditorEventCallback produces functions that can be passed to React components as event handlers. If you need to listen to events that originate within the contenteditable node, however, those event listeners need to be registered with the EditorView's handleDOMEvents prop.

You can use the useEditorEventListener hook to accomplish this. It takes an eventType and an event listener. The event listener follows the usual semantics for ProseMirror's handleDOMEvents prop:

• Returning true or calling event.preventDefault will prevent other listeners from running.
• Returning true will not automatically call event.preventDefault; if you want to prevent the default contenteditable behavior, you must call event.preventDefault.

You can use this hook to implement custom behavior in your NodeViews:

import { forwardRef, Ref } from "react";
import {
  useEditorEventListener,
  NodeViewComponentProps,
} from "@nytimes/react-prosemirror";

const Paragraph = forwardRef<HTMLParagraphElement, NodeViewComponentProps>(
  function Paragraph({ children, nodeProps, ...props }, ref) {
    useEditorEventListener("keydown", (view, event) => {
      const { pos, node } = nodeProps;

      if (event.code !== "ArrowDown") {
        return false;
      }
      const nodeEnd = pos + node.nodeSize;
      const { selection } = view.state;
      if (selection.anchor < pos || selection.anchor > nodeEnd) {
        return false;
      }
      event.preventDefault();
      alert("No down keys allowed!");
      return true;
    });

    return (
      <p ref={ref} {...props}>
        {children}
      </p>
    );
  }
);

Building node views with React

The other way to integrate React and ProseMirror is to have ProseMirror render node views using React components. Because React ProseMirror renders the ProseMirror document with React, node view components don't need to do anything special other than fulfill the NodeViewComponentProps interface.

import { forwardRef, Ref } from "react";
import {
  ProseMirror,
  ProseMirrorDoc,
  useEditorEventCallback,
  NodeViewComponentProps,
  reactKeys,
} from "@nytimes/react-prosemirror";
import { EditorState } from "prosemirror-state";
import { schema } from "prosemirror-schema-basic";

// Paragraph is more or less a normal React component, taking and rendering
// its children. All node view components _must_ forward refs to their top-level
// DOM elements. All node view components _should_ spread all of the props that they
// receive onto their top-level DOM elements; this is required for node Decorations
// that apply attributes rather than wrapping nodes in an additional element.
const Paragraph = forwardRef<HTMLParagraphElement, NodeViewComponentProps>(
  function Paragraph({ children, nodeProps, ...props }, ref) {
    const onClick = useEditorEventCallback((view) =>
      view.dispatch(view.state.tr.deleteSelection())
    );

    return (
      <p ref={ref} {...props} onClick={onClick}>
        {children}
      </p>
    );
  }
);

function ProseMirrorEditor() {
  return (
    <ProseMirror
      defaultState={EditorState.create({ schema, plugins: [reactKeys()] })}
      nodeViews={{
        paragraph: Paragraph,
      }}
    >
      <ProseMirrorDoc />
    </ProseMirror>
  );
}

What's changing in v2?

The upcoming v2 release constitutes a significant re-write of the library.

Previously, React ProseMirror relied on ProseMirror's EditorView to manage the DOM for the editor. To integrate it with React, we used React portals to render components into ProseMirror-managed DOM nodes, and a useLayoutEffect to sync state updates with the EditorView instance.

This approach provided some challenges. First, portals have to be rendered into existing, stable DOM nodes, so all React-based custom node views ended up wrapped in extra HTML elements. This made styling and producing valid DOM more challenging than it should be, and introduced corner cases in browser contenteditable implementations. Second, we induced a double render for every ProseMirror update, and during the first render, React-based custom node views will be rendered with the previous state. This is technically another form of the state tearing that this library was designed to prevent, as all other React components will be rendered with the new state!

To overcome these challenges, the new release moves rendering responsibility entirely into React. We disabled the EditorView's DOM update cycle, and implemented the same update algorithm that prosemirror-view uses with React components. The result is a more idiomatic, React-based library, which doesn't have any of the issues of the original implementation.

API changes

• The ProseMirror component API has changed slightly:
  • Instead of passing a mount prop with a ref to a child element, users must render a ProseMirrorDoc component as a child of the ProseMirror component.
  • The nodeViews prop no longer matches the ProseMirror API. Instead, nodeViews should be a map from node type name to React components, each of which must take NodeViewComponentProps as props. This map should be memoized, or defined outside the React component entirely.
  • To pass standard ProseMirror node view constructors, use the customNodeViews prop
• The API that React-based node views must implement has changed:
  • There is no longer any need to provide a ProseMirror node view constructor function. React-based node views are now just React components that accept NodeViewComponentProps as props.
  • Props related to the ProseMirror node, such as the node itself, the getPos function, and decorations, now live in the nodeProps property. All other props must be spread onto the root element of the node view component, aside from children, which may be rendered anywhere in the component, as appropriate.
  • All node view components must forward their ref to the root element of the component.
  • To implement features that would normally live in the node view spec, there are new hooks, such as useStopEvent and useSelectNode
• There is a new export, widget, which behaves similarly to Decoration.widget from prosemirror-view, but takes a React component instead of a toDOM method.

API

ProseMirror

type ProseMirror = (
  props: DirectEditorProps &
    ({ defaultState: EditorState } | { state: EditorState }) & {
      children: ReactNode;
      nodeViews?: {
        [nodeType: string]: ForwardRefExoticComponent<
          NodeViewComponentProps & RefAttributes<any>
        >;
      };
      customNodeViews?: {
        [nodeType: string]: NodeViewConstructor;
      };
    }
) => JSX.Element;

Renders the ProseMirror editor.

Example usage:

import { EditorState } from "prosemirror-state";
import {
  ProseMirror,
  ProseMirrorDoc,
  reactKeys,
} from "@nytimes/react-prosemirror";

export function ProseMirrorEditor() {
  return (
    <ProseMirror
      defaultState={EditorState.create({ schema, plugins: [reactKeys()] })}
    >
      <ProseMirrorDoc />
    </ProseMirror>
  );
}

ProseMirrorDoc

type ProseMirrorDoc = (props: { as?: ReactElement }) => JSX.Element;

Renders the actual editable ProseMirror document.

This must be passed as a child to the ProseMirror component. It may be wrapped in any other components, and other children may be passed before or after

Example usage:

import { EditorState } from "prosemirror-state";
import {
  ProseMirror,
  ProseMirrorDoc,
  reactKeys,
} from "@nytimes/react-prosemirror";

export function ProseMirrorEditor() {
  return (
    <ProseMirror
      defaultState={EditorState.create({ schema, plugins: [reactKeys()] })}
    >
      <ToolBar />
      <SomeWrapper>
        <ProseMirrorDoc as={<article />} />
      </SomeWrapper>
      <Footnotes />
    </ProseMirror>
  );
}

useEditorState

type useEditorState = () => EditorState | null;

Provides access to the current EditorState value.

useEditorEventCallback

type useEditorEventCallback = <T extends unknown[]>(
  callback: (view: EditorView | null, ...args: T) => void
) => void;

Returns a stable function reference to be used as an event handler callback.

The callback will be called with the EditorView instance as its first argument.

This hook is dependent on both the EditorContext.Provider and the LayoutGroup. It can only be used in a component that is mounted as a child of both of these providers.

useEditorEventListener

type useEditorEventListener = <EventType extends DOMEventMap>(
  eventType: EventType,
  listener: (view: EditorView, event: DOMEventMap[EventType]) => boolean
) => void;

Attaches an event listener at the EditorView's DOM node. See the ProseMirror docs for more details.

useEditorEffect

type useEditorEffect = (
  effect: (editorView: EditorView | null) => void | (() => void),
  dependencies?: React.DependencyList
) => void;

Registers a layout effect to run after the EditorView has been updated with the latest EditorState and Decorations.

Effects can take an EditorView instance as an argument. This hook should be used to execute layout effects that depend on the EditorView, such as for positioning DOM nodes based on ProseMirror positions.

Layout effects registered with this hook still fire synchronously after all DOM mutations, but they do so after the EditorView has been updated, even when the EditorView lives in an ancestor component.

Example usage:

import { useRef } from "react"
import { useEditorEffect } from "@nytimes/react-prosemirror"

export function SelectionWidget() {
  const ref = useRef()

  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;
  })

  return (
    <div
      ref={ref}
      style={{
        position: "absolute"
      }}
    />
  )
}

NodeViewComponentProps

type NodeViewComponentProps = {
  nodeProps: {
    decorations: readonly Decoration[];
    innerDecorations: DecorationSource;
    node: Node;
    children?: ReactNode | ReactNode[];
    getPos: () => number;
  };
} & HTMLAttributes<HTMLElement>;

The props that will be passed to all node view components. These props map directly to the arguments passed to NodeViewConstructor functions by the default ProseMirror EditorView implementation.

Node view components may also be passed any other valid HTML attribute props, and should pass them through to their top-level DOM element. See the above example for more details.

In addition to accepting these props, all node view components must forward their ref to their top-level DOM element.

useStopEvent

type useStopEvent = (stopEvent: (view: EditorView, event: Event) => boolean): void

This hook can be used within a node view component to register a stopEvent handler. Events for which this returns true are not handled by the editor.

useSelectNode

type useSelectNode = (selectNode: () => void, deselectNode?: () => void): void

This hook can be used within a node view component to register selectNode and deselectNode handlers. The selectNode handler will only be called when a NodeSelection is created whose node is this one.

widget

type widget = (
  pos: number,
  component: ForwardRefExoticComponent<
    RefAttributes<HTMLElement> & WidgetComponentProps
  >,
  spec?: ReactWidgetSpec
) => Decoration(pos, pos, new ReactWidgetType(component, spec))

Like ProseMirror View's Decoration.widget, but with support for React components.