); } // ProseMirrorEditor.tsx import { ProseMirror, ProseMirrorDoc, reactKeys } from "@handlewithcare/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 ( { setEditorState(s => s.apply(tr)) }} > {/* We have to mount all components that need to access the EditorView as children of the ProseMirror component */} ); } ``` #### `useEditorEventCallback` It's also often necessary to dispatch transactions or execute side effects in response to user actions, like mouse clicks and keyboard events. You can use `useEditorEventCallback` to create a stable function reference that can safely access the latest value of the `EditorView`. _Note_: if you need to respond to keyboard events from _within_ the `contenteditable` element, you should instead use [`useEditorEventListener`](#useEditorEventListener). ```tsx // BoldButton.tsx import { toggleMark } from "prosemirror-commands"; import { useEditorEventCallback } from "@handlewithcare/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 ; } // ProseMirrorEditor.tsx import { ProseMirror, ProseMirrorDoc, reactKeys, } from "@handlewithcare/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 ( { setEditorState((s) => s.apply(tr)); }} > {/* We have to mount all components that need to access the EditorView as children of the ProseMirror component */} ); } ``` #### `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 node views: ```tsx import { useEditorEventListener, NodeViewComponentProps, useMergedDOMRefs, } from "@handlewithcare/react-prosemirror"; function Paragraph({ children, nodeProps, ref, ...props }) { 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 (

{children}

); } ``` ### 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`](#nodeviewcomponentprops) interface. ```tsx import { ProseMirror, ProseMirrorDoc, useEditorEventCallback, NodeViewComponentProps, useMergedDOMRefs, reactKeys, } from "@handlewithcare/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. Some guidelines: // // - All node view components _must_ pass refs to their top-level // DOM elements. // - All node view components that render children _must_ pass nodeProps.contentDOMRef // to the parent element of `children`. If this is also the top-level DOM // element, use `useMergedDOMRefs` to apply both refs // - 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. // // Note: we are accessing `ref` as a prop here, which has been available since React 19. // If you are using React <=18, you will need to use forwardRef to access `ref`. function Paragraph({ children, nodeProps, ref, ...props }) { const onClick = useEditorEventCallback((view) => view.dispatch(view.state.tr.deleteSelection()) ); return (

{children}

); } // **IMPORTANT**: Define nodeViewComponents _outside_ of your editor // component. It should be a stable reference. // // If you need to define it within a React component for some reason, // ensure that it is properly memoized with `useMemo` or the React Compiler. const nodeViewComponents = { paragraph: Paragraph, }; function ProseMirrorEditor() { return ( ); } ``` If your node view component is more complex, and the top level DOM element does not directly render `children`, use `ref` and `nodeProps.contentDOMRef` separately: ```tsx function FancyParagraph({ children, nodeProps, ref, ...props }) { const onClick = useEditorEventCallback((view) => view.dispatch(view.state.tr.deleteSelection()) ); return (

{children}

); } ``` ## API ### `ProseMirror` ```tsx type ProseMirror = ( props: DirectEditorProps & ({ defaultState: EditorState } | { state: EditorState }) & { children: ReactNode; nodeViewComponents?: { [nodeType: string]: ComponentType; }; nodeViews?: { [nodeType: string]: NodeViewConstructor; }; markViewComponents?: { [markType: string]: ComponentType; }; markViews?: { [markType: string]: MarkViewConstructor; }; } ) => JSX.Element; ``` Renders the ProseMirror editor. Example usage: ```tsx import { EditorState } from "prosemirror-state"; import { ProseMirror, ProseMirrorDoc, reactKeys, } from "@handlewithcare/react-prosemirror"; export function ProseMirrorEditor() { return ( ); } ``` ### `ProseMirrorDoc` ```tsx 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: ```tsx import { EditorState } from "prosemirror-state"; import { ProseMirror, ProseMirrorDoc, reactKeys, } from "@handlewithcare/react-prosemirror"; export function ProseMirrorEditor() { return ( ); } ``` ### `useEditorState` ```tsx type useEditorState = () => EditorState | null; ``` Provides access to the current EditorState value. ### `useEditorEventCallback` ```tsx type useEditorEventCallback = ( 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` ```tsx type useEditorEventListener = ( eventType: EventType, listener: (view: EditorView, event: DOMEventMap[EventType]) => boolean ) => void; ``` Attaches an event listener at the `EditorView`'s DOM node. See [the ProseMirror docs](https://prosemirror.net/docs/ref/#view.EditorProps.handleDOMEvents) for more details. ### `useEditorEffect` ```tsx 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: ```tsx import { useRef } from "react" import { useEditorEffect } from "@handlewithcare/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 (

) } ``` ### `NodeViewComponentProps` ```tsx interface NodeViewComponentProps extends AllHTMLAttributes = { nodeProps: { decorations: readonly Decoration[]; innerDecorations: DecorationSource; node: Node; getPos: () => number; contentDOMRef: Exclude, null>; }; ref: LegacyRef; }; ``` The props that will be passed to all node view components. These props map directly to the arguments passed to [`NodeViewConstructor` functions](https://prosemirror.net/docs/ref/#view.NodeViewConstructor) 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. In addition to accepting these props, all node view components _must_ pass their ref to their top-level DOM element. All node view components that render their `children` _must_ pass `nodeProps.contentDOMRef` to the parent element of `children`. [See the above example](#building-node-views-with-react) for more details. ### `useNodePos` ```ts type useNodePos = () => number; ``` Like prosemirror-view’s `NodeViewConstructor` API, React ProseMirror passes a `getPos` function to all node view components. This function will return the current position of the node in the document. `getPos` is guaranteed to always return the correct value for the current node, but it will not subscribe a node view component to updates to its position. This means that _it is only safe to use `getPos` in a callback or effect_. It is _not_ safe to use in a render function, because changes to the node's position will not trigger a re-render of the node view component. It’s best to avoid relying on the node’s position in the render function, because that will require that your node view component re-render on every update to the document. But if you have an infrequently used node, or small enough documents that you don't have to worry about this, you can use the `useNodePos` function to get an up-to-date node position after every document update. ### `useStopEvent` ```tsx type useStopEvent = (stopEvent: (view: EditorView, event: Event) => boolean): void ``` This hook can be used within a node view component to register a [stopEvent handler](https://prosemirror.net/docs/ref/#view.NodeView.stopEvent). Events for which this returns true are not handled by the editor. ### `useIgnoreMutation` ```tsx type useIgnoreMutation = (stopEvent: (view: EditorView, mutation: ViewMutationRecord) => boolean): void ``` This hook can be used within a node view component to register an [ignoreMutation handler](https://prosemirror.net/docs/ref/#view.NodeView.ignoreMutation). Mutations for which this returns true are not handled by the editor. ### `useSelectNode` ```tsx type useSelectNode = (selectNode: () => void, deselectNode?: () => void): void ``` This hook can be used within a node view component to register [selectNode and deselectNode handlers](https://prosemirror.net/docs/ref/#view.NodeView.selectNode). The selectNode handler will only be called when a NodeSelection is created whose node is this one. ### `useIsNodeSelected` ```tsx type useIsNodeSelected = (): boolean ``` This hook can be used within a node view component to subscribe to a boolean value determining whether this node is selected. The hook will return true when a NodeSelection is created whose node is this one. ### `widget` ```ts type widget = ( pos: number, component: ForwardRefExoticComponent< RefAttributes & WidgetComponentProps >, spec?: ReactWidgetSpec ) => Decoration(pos, pos, new ReactWidgetType(component, spec)) ``` Like ProseMirror View's `Decoration.widget`, but with support for React components. ### `reorderSiblings` A [command](https://prosemirror.net/docs/ref/#state.Command) creator that can be used to reorder adjacent nodes in a document. The command creator takes two arguments: - `pos` — The `start` position of the parent of the nodes being reordered - `order` — The new order for the nodes, expressed as an array of indices. For example, to swap the first two nodes in a set of three, `order` would be set to `[1, 0, 2]`. To move the first node to the end, and keep the other two in relative order, set `order` to `[1, 2, 0]`. ```ts type reorderSiblings = (pos: number, order: number[]): Command ``` #### When should I use this? In order to maintain the React state across node view components, React ProseMirror uses the `reactKeys` plugin to track node positions across transactions and provide them with stable keys. During a reorder, for example when two nodes are swapped, ProseMirror is unable to track the positions across the resulting delete and insert steps, and so the `reactKeys` plugin will assign new keys to the nodes, causing their node view components to be remounted. Sometimes, such as when using a drag-and-drop library like `framer-motion`, remounting the component being dragged can cause issues. The `reorderSiblings` command provides additional metadata to React ProseMirror that allows it to properly track the new positions for the reordered nodes, allowing it to reuse the same keys. This prevents any issues that could be caused by unexpected component remounts. ## Migrations - [Migrating from v1 to v2](migration-guides/v2.md) - [Migrating from v2 to v3](migration-guides/v3.md) ## Looking for someone to collaborate with? Reach out to [Handle with Care](https://handlewithcare.dev/#get-in-touch)! We're a product development collective with years of experience bringing excellent ideas to life. We love React and ProseMirror, and we're always looking for new folks to work with!