API Reference#

createEditor(options)#

Builds an editor without mounting it. The DOM host comes later from editorContent(), which owns the mount/unmount lifecycle of the element it is applied to — passing element here would mount twice.

import { createEditor } from "@domphy/editor/domphy"

const editor = createEditor({
  extensions: [starterKit()],
  content: "<p>Hello</p>",
  editable: true,
  onUpdate: ({ editor }) => console.log(editor.getJSON()),
})

Options can be changed after construction with editor.setOptions(partial).

transaction on onUpdate is what makes a loop guard possible: tag your own programmatic writes and ignore them on the way back out, so syncing to a server does not re-trigger itself.

const editor = createEditor({
  onUpdate: ({ editor, transaction }) => {
    if (transaction.getMeta("fromServer")) return
    save(editor.getJSON())
  },
})

// Applying a remote change without tripping the save above:
editor.chain().setMeta("fromServer", true).setContent(incoming).run()

Editor instance#

Commands#

chain() builds one transaction shared by every link. Each link runs and pushes its boolean result; a failing link does not abort the chain. run() dispatches once and returns true only if every link returned true.

editor.chain().focus().toggleBold().run()          // one transaction, one history entry
editor.commands.toggleBold()                       // its own transaction, dispatched immediately
editor.can().toggleBold()                          // would it apply? nothing is mutated
editor.can().chain().toggleBold().toggleItalic().run()

Every extension command is built out of this generic set, which is always available:

A command receives { editor, tr, state, dispatch, chain, can, commands } and returns whether it applied. dispatch is undefined during can(), so guard every mutation with it.

setMeta("preventUpdate", true) suppresses the update event for that transaction; the event is also skipped when the document did not actually change.

Document JSON#

The JSON is Tiptap's, exactly:

{
  "type": "doc",
  "content": [
    { "type": "heading", "attrs": { "level": 2 }, "content": [{ "type": "text", "text": "Title" }] },
    { "type": "paragraph", "content": [{ "type": "text", "marks": [{ "type": "bold" }], "text": "Bold" }] },
    { "type": "paragraph" }
  ]
}

Marks live on text nodes, never on wrappers. attrs is omitted when every attribute is at its default, and an empty content array is omitted entirely — an empty paragraph is just { "type": "paragraph" }.

Positions are ProseMirror-style integer token positions: entering a non-leaf node costs 1, each character costs 1, a leaf node (hardBreak, horizontalRule) costs 1, leaving a node costs 1. This is what makes from/to and command semantics source-compatible with Tiptap.

Node views#

addNodeView on a Node hands rendering of that node to you. The instance is plain DOM — there is no framework wrapper and no Domphy element tree here, because the editor treats the returned subtree as an imperative island it must not reconcile.

import { Node } from "@domphy/editor"

const Chip = Node.create({
  name: "chip",
  group: "inline",
  inline: true,
  atom: true,

  addAttributes() {
    return { label: { default: "chip" } }
  },

  parseHTML() {
    return [{ tag: "span[data-chip]" }]
  },

  renderHTML({ HTMLAttributes }) {
    return ["span", { ...HTMLAttributes, "data-chip": "" }]
  },

  addNodeView() {
    return ({ node, selected, updateAttributes }) => {
      const dom = document.createElement("span")
      dom.dataset.chip = ""
      dom.textContent = String(node.attrs?.label ?? "")
      dom.addEventListener("click", () => updateAttributes({ label: "clicked" }))

      return {
        dom,
        update(next) {
          // Same node type: repaint in place instead of rebuilding.
          if (next.type !== "chip") return false
          dom.textContent = String(next.attrs?.label ?? "")
          return true
        },
        selectNode: () => dom.classList.add("is-selected"),
        deselectNode: () => dom.classList.remove("is-selected"),
      }
    }
  },
})

addNodeView() runs once per extension and returns the factory; the factory runs per node instance with NodeViewProps:

The returned NodeViewInstance:

Two ceilings are worth knowing before you lean on this.

Identity is positional. A rendering pass rebuilds the tree, and an instance is reused when a node of the same type sits at the same child-index path as last render. That covers the common case — attributes change and update() repaints in place — but inserting a sibling before a node view hands that instance to its neighbour. If your view holds state that must not migrate (a media element mid-playback, a third-party widget), check identity yourself in update() and return false when it does not match; the editor then destroys and rebuilds, which is always correct.

selected is range coverage, not a node selection. There is no NodeSelection, so clicking an atom node does not select it — only a text range that spans the node sets selected. Click-to-select has to be built in your own dom handler.

Domphy adapter#

editorContent(editor, props?)#

Mounts the editor into the host element and styles the editing surface with theme tokens. Apply it to a div.

{ div: null, $: [editorContent(editor, { minHeight: 60 })] }

The mount runs through a behavior(), so it happens exactly once for the real DOM node no matter how many times a reactive ancestor re-renders the host; passing a different editor later swaps the view in place, and unmount runs once when the element leaves the DOM.

Typography inside the editable area is left to the theme and the browser's tag defaults — the content is real p / h1-h6 / strong / em markup, so it inherits the document type scale. Only structural rhythm (block margins, list indent, quote and code chrome) is declared by the patch.

bubbleMenu(editor, props)#

A floating menu anchored to the current text selection. Apply it to the same host element as editorContent().

{
  div: null,
  $: [
    editorContent(editor),
    bubbleMenu(editor, {
      shouldShow: (editor) => !editor.state.selection.empty && !editor.isActive("codeBlock"),
      children: { div: [boldButton, italicButton] },
    }),
  ],
}

Positioning uses @domphy/floating against a virtual element wrapping the live selection rectangle: getBoundingClientRect() re-reads getSelection().getRangeAt(0) on every call, so scrolling and resizing reposition against the real current rect rather than a snapshot taken when the menu opened. The middleware chain is inline() (picks the right rect when a selection wraps across lines), offset(8), flip() and shift().

Show/hide is wired to the editor's selectionUpdate, update, focus and blur events from inside the behavior — not from a lifecycle hook — so it survives host re-renders. Destroying the editor also tears the panel down. The panel is portaled into a document/root overlay (never a child of the contenteditable host, which EditorView.render() wipes), escaping the editor's overflow and stacking context, and it swallows mousedown so pressing a button never blurs the editor and collapses the selection you are formatting.

editorState(editor)#

Returns reader functions that re-evaluate on every transaction.

const { isActive, read } = editorState(editor)

isActive("bold")                        // (l) => boolean
isActive("heading", { level: 2 })       // (l) => boolean
read((editor) => editor.can().undo())   // (l) => boolean
read((editor) => editor.getText())      // (l) => string

There is nothing more to it than reading editor.stateVersion with the listener first, so anything not covered here can be written inline:

const wordCount = (l) => {
  editor.stateVersion.get(l)
  return editor.getText().split(/\s+/).filter(Boolean).length
}

Deviations from Tiptap#

Names and semantics match Tiptap, but the engine underneath is not ProseMirror, and a handful of behaviours differ. These are the ones that can change what your code does — read them before porting a non-trivial Tiptap integration.

Whole features that are absent rather than merely different — mark views, paste rules, registerPlugin, NodePos, collaboration, gapcursor, dropcursor — are listed under Coming from Tiptap.