Quick start
Put a working GoTipe editor on the page with React, Markdown, a headless setup or Vue.
Four ways to get an editor running. The first two use the ready UI from @gotipe/block-editor (commercial); the last two use only MIT packages and your own controls. All four run on the JS engine, so they need no WebAssembly setup. If your bundler reports that it can't resolve @gotipe/wasm, add the alias from installation.
Install
For BlockEditor or PageEditor:
npm install @gotipe/block-editor @gotipe/core @gotipe/react @gotipe/theme @gotipe/i18n @gotipe/markdown @gotipe/suggestions react react-dompnpm add @gotipe/block-editor @gotipe/core @gotipe/react @gotipe/theme @gotipe/i18n @gotipe/markdown @gotipe/suggestions react react-domyarn add @gotipe/block-editor @gotipe/core @gotipe/react @gotipe/theme @gotipe/i18n @gotipe/markdown @gotipe/suggestions react react-dombun add @gotipe/block-editor @gotipe/core @gotipe/react @gotipe/theme @gotipe/i18n @gotipe/markdown @gotipe/suggestions react react-domFor a headless React editor:
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-domFor Vue:
npm install @gotipe/core @gotipe/vue vuepnpm add @gotipe/core @gotipe/vue vueyarn add @gotipe/core @gotipe/vue vuebun add @gotipe/core @gotipe/vue vueCreate an editor
Editor.tsxPage.tsxEditor.tsxEditor.vue
import { BlockEditor } from "@gotipe/block-editor";
import { FullPreset } from "@gotipe/core/presets";
import { useEditor } from "@gotipe/react";
import "@gotipe/theme/base.css";
import "@gotipe/theme/theme.css";
const INITIAL = {
version: 1,
blocks: [
{
id: "title",
type: "heading",
attrs: { level: 1 },
content: [{ text: "Welcome", marks: [] }],
children: [],
},
{
id: "intro",
type: "paragraph",
attrs: {},
content: [
{ text: "Type ", marks: [] },
{ text: "/", marks: [{ type: "code", attrs: {} }] },
{ text: " to insert a block.", marks: [] },
],
children: [],
},
],
};
export function Editor() {
const editor = useEditor({
extensions: [FullPreset],
content: INITIAL,
engine: "js",
onUpdate: ({ editor }) => localStorage.setItem("doc", JSON.stringify(editor.getJSON())),
});
return <BlockEditor editor={editor} showAiCommandBar={false} />;
}import { PageEditor } from "@gotipe/block-editor";
import { useState } from "react";
import "@gotipe/theme/base.css";
import "@gotipe/theme/theme.css";
export function Page() {
const [markdown, setMarkdown] = useState("# Release notes\n\nStart writing.\n");
return (
<>
<PageEditor markdown={markdown} onChange={setMarkdown} />
<pre>{markdown}</pre>
</>
);
}import type { GoTipeEditor } from "@gotipe/core";
import { DefaultPreset } from "@gotipe/core/presets";
import { EditorContent, useEditor, useEditorState } from "@gotipe/react";
import type { MouseEvent } from "react";
// Keep the caret in the document when a button is pressed.
const keepFocus = (event: MouseEvent) => event.preventDefault();
function Toolbar({ editor }: { editor: GoTipeEditor }) {
const toolbar = useEditorState(editor, (state) => state.toolbar);
const marks = toolbar?.activeMarks ?? [];
return (
<div role="toolbar" aria-label="Formatting">
<button
type="button"
aria-pressed={marks.includes("bold")}
onMouseDown={keepFocus}
onClick={() => editor.chain().focus().toggleBold().run()}
>
Bold
</button>
<button
type="button"
aria-pressed={marks.includes("italic")}
onMouseDown={keepFocus}
onClick={() => editor.chain().focus().toggleItalic().run()}
>
Italic
</button>
<button
type="button"
onMouseDown={keepFocus}
onClick={() => editor.chain().focus().setBlockType("heading", { level: 2 }).run()}
>
Heading
</button>
<button
type="button"
onMouseDown={keepFocus}
onClick={() => editor.chain().focus().toggleBulletList().run()}
>
List
</button>
<button
type="button"
disabled={!toolbar?.canUndo}
onMouseDown={keepFocus}
onClick={() => editor.chain().focus().undo().run()}
>
Undo
</button>
</div>
);
}
export function Editor() {
const editor = useEditor({
extensions: [DefaultPreset],
engine: "js",
content: {
version: 1,
blocks: [
{
id: "intro",
type: "paragraph",
attrs: {},
content: [{ text: "Select some text and press Bold.", marks: [] }],
children: [],
},
],
},
});
if (!editor) return null;
return (
<>
<Toolbar editor={editor} />
<EditorContent editor={editor} ariaLabel="Document" />
</>
);
}<script setup lang="ts">
import { DefaultPreset } from "@gotipe/core/presets";
import { EditorContent, useEditor, useEditorState } from "@gotipe/vue";
const editor = useEditor({
extensions: [DefaultPreset],
engine: "js",
content: {
version: 1,
blocks: [
{
id: "intro",
type: "paragraph",
attrs: {},
content: [{ text: "Hello from Vue.", marks: [] }],
children: [],
},
],
},
});
const marks = useEditorState(editor, (state) => state.toolbar.activeMarks);
function toggleBold() {
editor.value?.chain().focus().toggleBold().run();
}
</script>
<template>
<button
type="button"
:aria-pressed="marks?.includes('bold')"
@mousedown.prevent
@click="toggleBold"
>
Bold
</button>
<EditorContent :editor="editor" aria-label="Document" />
</template>What happens here:
useEditorcreates the editor once, when the component mounts, and destroys it on unmount. It returnsnull(React) or a ref holdingnull(Vue) until the editor is ready. Options are read once; later changes to them are ignored.BlockEditorshows a loading skeleton whileeditorisnull.showAiCommandBaris turned off here; without the AI extensions the editor shows no AI controls anyway.PageEditorcreates its own editor. After edits it callsonChangewith the whole Markdown text, at most once per animation frame; debounce saving in your code. Blocks you did not touch keep their original bytes.EditorContentmounts the editor on its element and renders the blocks. Toolbar buttons call commands;focus()returns the caret to the document before the command runs.EditorContentshows images and files read-only. To upload, resize, crop or caption them, wrap it in<MediaBlocksContext.Provider value={mediaBlocks}>withmediaBlocksfrom@gotipe/react/media(see React);BlockEditorandPageEditoralready include it.
Editor options
useEditor takes the options of createEditor from @gotipe/core:
| Option | Type | Default | Description |
|---|---|---|---|
extensions |
( |
required | Block types, marks and behaviour. Presets are arrays and mix with single extensions. |
content |
object | string |
one empty paragraph | Document JSON, or an HTML string (browser only). See content formats. |
editable |
boolean |
true |
false blocks user input. Commands and dispatch still work. |
autofocus |
boolean | "start" | "end" |
false |
Focus the surface when it is mounted: "start" puts the caret at the start of the first block with text, "end" at the end of the last one, true where the editor starts, the start of the first block. Same as editor.. |
engine |
"auto" | "js" | "wasm" |
"auto" |
Which engine runs the document. See engines. |
host |
EditorHost |
{} |
Asset storage, links and errors. See host. |
onCreate, onUpdate, on, onFocus, onBlur, onDestroy |
( |
— | Listeners for the matching events. |
The presets come from @gotipe/core/presets:
| Preset | Contents |
|---|---|
MinimalPreset |
Paragraph, bold, italic, history |
DefaultPreset |
Paragraphs, headings, bullet, numbered and to-do lists, code blocks, images, quotes, callouts, dividers, tables, toggles; bold, italic, underline, strikethrough, inline code, links, highlight, text colour; history, placeholder, slash commands |
FullPreset |
DefaultPreset plus columns, embeds, math, files, superscript and subscript |
Next steps
- Document model: what
contentandgetJSON()contain. - BlockEditor and PageEditor props.
- React and Vue adapters in depth.