Skip to content
Edit on GitHub

React

The MIT React adapter: useEditor, useEditorStatus and useEditorState, the Editor and EditorContent renderer, BubbleMenu and FloatingMenu, custom block views and server rendering.

@gotipe/reactMIT

@gotipe/react creates and destroys the editor with your component, subscribes to its state and renders the document as React elements, including the table controls. Images and files are shown read-only; their editing UI is the separate @gotipe/react/media entry. It ships no CSS. The ready BlockEditor and PageEditor are built on it.

Install

npm install @gotipe/core @gotipe/react react react-dom

React 18 or newer. @gotipe/i18n comes with the adapter.

Example

NotesEditor.tsx
import { DefaultPreset } from "@gotipe/core/presets";
import { Editor, useEditor, useEditorState } from "@gotipe/react";

export function NotesEditor() {
  const editor = useEditor({
    extensions: [DefaultPreset],
    content: "<h1>Notes</h1><p>Select a word and press Bold.</p>",
    onUpdate: ({ editor }) => localStorage.setItem("notes", editor.getMarkdown()),
  });
  const bold = useEditorState(editor, (state) => state.toolbar.activeMarks.includes("bold"));

  return (
    <div>
      <button
        type="button"
        aria-pressed={bold ?? false}
        disabled={!editor}
        onMouseDown={(event) => event.preventDefault()}
        onClick={() => editor?.chain().focus().toggleBold().run()}
      >
        Bold
      </button>
      <Editor editor={editor} ariaLabel="Notes" />
    </div>
  );
}
Live editorYour own buttons
Loading the editor…

onMouseDown with preventDefault keeps the selection in the document while you click. Images and files in this editor are read-only until you provide @gotipe/react/media; see Image and file editing.

Hooks

Hook Returns Description
useEditor(options) GoTipeEditor | null Creates the editor after mount, destroys it on unmount. null until it exists.
useEditorStatus(options) { editor, error } The same editor, and why it could not be created; see Creation errors.
useEditorState(editor, selector, isEqual?) T | undefined Re-renders when selector(viewState) changes. isEqual compares results (default Object.is).
useEditorContext() GoTipeEditor The editor of the surrounding Editor; throws outside it.
useGoTipeI18n() I18n UI strings; English without a provider.
useFloatingPosition(options) position or null Places a panel by an anchor inside the visible viewport and follows scroll and resize.

useEditor and useEditorStatus take the options of createEditor (see quick start) and onError. They read the editor options once, when they create the editor: later changes to content or callbacks are ignored, so call editor.setContent() or subscribe with editor.on(). onError is read when a failure arrives, so the latest one is used. In Strict Mode, an editor that finishes after the first unmount is destroyed.

Selectors run on every view change, so return small values; with an object, pass isEqual.

Creation errors

Creating the editor can fail: WASM_INIT_FAILED with engine: "wasm", VALIDATION_ERROR for a JSON document the schema rejects, EXTENSION_DEPENDENCY_CYCLE. useEditorStatus returns the editor with the reason. error is null while the editor is created and once it exists, and an Error when creation failed; a GoTipeError also has a code. Both hooks pass the failure to onError(error) once; without onError, they log it to the console.

NotesEditor.tsx
import { DefaultPreset } from "@gotipe/core/presets";
import { Editor, useEditorStatus } from "@gotipe/react";

export function NotesEditor({ report }: { report: (error: Error) => void }) {
  const { editor, error } = useEditorStatus({
    extensions: [DefaultPreset],
    engine: "wasm",
    onError: report,
  });

  if (error) return <p role="alert">The editor could not start: {error.message}</p>;
  return <Editor editor={editor} ariaLabel="Notes" />;
}

onError reports only the creation. Errors of a working editor, such as a failed upload, a blocked link or a paste that does not fit, go to host.onError and the error event; see Errors.

A creation that fails after unmount reports nothing, so Strict Mode, which creates the editor twice, reports a failure once. When React runs the hook's effect again, after Fast Refresh or when an Activity is shown again, the editor is created anew from the current options and the previous error is cleared.

Components

Component Props Description
Editor editor, blockViews, blockRenderer, placeholder, afterText, ariaLabel, slotBefore, slotAfter, className, style, children .gotipe-editor with context, the document and slots. Renders nothing while editor is null.
EditorContent editor, blockViews, blockRenderer, placeholder, afterText, ariaLabel Only the document surface; it mounts the editor on its element.
BubbleMenu editor, children, shouldShow, offset, className, ariaLabel A toolbar above a selection in an editable editor.
FloatingMenu editor, children, shouldShow, ariaLabel A toolbar left of the focused, empty paragraph under a collapsed caret.
GoTipeI18nProvider locale or i18n, children UI language; see i18n.

Without ariaLabel, the document and both menus are named in the language of GoTipeI18nProvider — a11y.editorLabel, a11y.toolbarLabel and a11y.insertLabel: "Document content", "Text formatting" and "Insert block" in English and without a provider; see i18n.

children of both menus can be a function ({ editor }) => ReactNode. BubbleMenu renders into a layer on <body> that copies the editor's --gt-* tokens, font and direction. Clicks inside both menus keep the document's selection.

FormattingBubble.tsx
import type { GoTipeEditor } from "@gotipe/core";
import { BubbleMenu } from "@gotipe/react";

export function FormattingBubble({ editor }: { editor: GoTipeEditor }) {
  return (
    <BubbleMenu editor={editor} ariaLabel="Formatting">
      <button type="button" onClick={() => editor.chain().focus().toggleItalic().run()}>
        Italic
      </button>
    </BubbleMenu>
  );
}

Block views

blockViews replaces the view of a block type. A view gets BlockViewProps and must spread rootProps on its root element (block id and decorations) and set data-block-type:

Quote.tsx
import type { BlockViewProps } from "@gotipe/react";

export function Quote({ block, rootProps, content, children }: BlockViewProps) {
  const className = ["pull-quote", rootProps.className].filter(Boolean).join(" ");
  return (
    <blockquote {...rootProps} data-block-type={block.type} className={className}>
      {content}
      {children}
    </blockquote>
  );
}

// <Editor editor={editor} blockViews={{ blockquote: Quote }} />
Prop Type Description
block BlockView The block: id, type, attrs, content, children.
editor GoTipeEditor The editor.
content ReactNode The block's text with marks and decorations.
children ReactNode Child blocks, rendered by the editor.
rootProps Record<string, unknown> Attributes the root must carry.
readOnly boolean The editor is read-only.
phantom boolean Drawn as a suggested block that cannot be edited (usePhantom() reads it too).
isSelected, selectedBlockId, parentType Selection and nesting.

placeholder is (block, parentType) => string | null and replaces the empty-block hints; by default they come from the placeholder.* strings. blockRenderer is an older wrapper API; prefer blockViews.

afterText (AfterTextFn) is (block) => ReactNode: what a block with text shows right after its last character, inside its element — BlockEditor draws the docs view's heading anchors with it. The node is wrapped as a widget (data-gotipe-widget, not editable): it is not part of the document's text, offsets or copy, and the caret never enters it. A block without text and a suggested block show nothing. A custom view gets it inside content.

A block type with no view, such as your own node without blockViews, is drawn as a <p> with its text; with child blocks, as a <div> with its text and then the children.

The building blocks of the default views are exported for your own views: TableBlock, TableColumnResizeHandle, CodeBlock, ToggleBlock, CalloutBlock, TextRenderer and FloatingPortal; ImageBlock and FileBlock come from @gotipe/react/media. useResolvedAsset and saveAssetWithHost go through the host asset callbacks.

Image and file editing

EditorContent shows images and files as the reader sees them: the picture with its width and caption, the failed state, and a file card whose name opens or downloads the file. Editing them (upload, link, resize, crop, caption, alt text, preview and the image actions menu) lives in @gotipe/react/media, so an app that only displays documents does not load it. Turn it on with MediaBlocksContext:

MediaEditor.tsx
import type { GoTipeEditor } from "@gotipe/core";
import { Editor, MediaBlocksContext } from "@gotipe/react";
import { mediaBlocks } from "@gotipe/react/media";

export function MediaEditor({ editor }: { editor: GoTipeEditor | null }) {
  return (
    <MediaBlocksContext.Provider value={mediaBlocks}>
      <Editor editor={editor} />
    </MediaBlocksContext.Provider>
  );
}

BlockEditor and PageEditor provide it themselves. @gotipe/react/media also exports ImageBlock and FileBlock for your own block views; MediaBlocks and MediaBlockProps type a replacement pair.

Server rendering

The editor is created in an effect, so a server render outputs no document and creates nothing: useEditorStatus returns { editor: null, error: null }, Editor renders nothing and BlockEditor renders its loading skeleton. To serve the content as HTML, render it with renderToHtml from @gotipe/core/server and replace it on the client.

Note:

The packages carry no "use client" directive. In a framework with React Server Components, import them from a client component.

Limitations

  • A failed creation is not tried again by itself. To retry, mount the component anew, for example with a new key.
  • Changing content, extensions or engine after mount does not create a new editor; the hooks read the options only when they create one.