React
The MIT React adapter: useEditor, useEditorStatus and useEditorState, the Editor and EditorContent renderer, BubbleMenu and FloatingMenu, custom block views and server rendering.
@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-dompnpm add @gotipe/core @gotipe/react react react-domyarn add @gotipe/core @gotipe/react react react-dombun add @gotipe/core @gotipe/react react react-domReact 18 or newer. @gotipe/i18n comes with the adapter.
Example
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>
);
}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 |
|---|---|---|
use |
Go |
Creates the editor after mount, destroys it on unmount. null until it exists. |
use |
{ editor, error } |
The same editor, and why it could not be created; see Creation errors. |
use |
T | undefined |
Re-renders when selector( changes. isEqual compares results (default Object.is). |
use |
GoTipeEditor |
The editor of the surrounding Editor; throws outside it. |
useGoTipeI18n() |
I18n |
UI strings; English without a provider. |
use |
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.
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. |
Go |
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.
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:
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< |
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:
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.
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,extensionsorengineafter mount does not create a new editor; the hooks read the options only when they create one.