tiptap-notion-editor

A Notion-style rich text editor built on Tiptap 3.

Slash commands, bubble menus, block drag-and-drop, tables with handles, image upload, math (KaTeX), emoji, @mention and a table of contents in the margin.

Install

pnpm add tiptap-notion-editor

Peer dependencies must already exist in the host app — that is deliberate, not an oversight: bundling @tiptap/* would create a second ProseMirror instance, and schemas from two different instances do not recognise each other.

pnpm add @tiptap/core @tiptap/pm @tiptap/react react react-dom

Usage

import { NotionEditor } from "tiptap-notion-editor";
import "tiptap-notion-editor/style.css";

export function PageEditor({ page }) {
  return (
    <NotionEditor
      key={page.id}
      content={page.content}
      onChange={(json) => savePage(page.id, json)}
      uploadImage={async (file) => {
        const url = await uploadToStorage(file);
        return url;
      }}
      mentionSource={async (query) => {
        const users = await searchUsers(query);
        return users.map((u) => ({ id: u.id, label: u.fullName }));
      }}
    />
  );
}

Tailwind

The components use Tailwind utility classes, and those classes are compiled by the host app — they are not baked into style.css. Add this line to the app's CSS entry file, right after @import "tailwindcss":

@source "../node_modules/tiptap-notion-editor/lib/*.js";

Without it the editor still runs, but with almost no styling.

The editor also reads the app's theme variables (--color-background, --color-border, --color-primary…). Any variable you leave undefined falls back to the default in lib/styles/tokens.css.

Content width

The content column stretches to fill whatever space it is given, reserving 96px on each side for the drag handles and the table of contents. To pin it to a fixed reading width instead, override the grid track in your own CSS:

.notion-like-editor-layout {
  --content-width: minmax(auto, 708px);
}

Language

The default is Vietnamese. Change it with the locale prop:

<NotionEditor locale="en" />

Both the vi and en dictionaries are exported, so the host app can override individual strings without forking the package:

import { NotionEditor, getMessages, type Messages } from "tiptap-notion-editor";

const t: Messages = getMessages("en");
const custom: Messages = {
  ...t,
  slash: { ...t.slash, groups: { ...t.slash.groups, insert: "Add" } },
};

The Messages type is derived from the Vietnamese dictionary, so a missing key in another translation is a compile error rather than an empty string at runtime.

Props

| Prop | Type | Default | Meaning | | --- | --- | --- | --- | | content | JSONContent \| string | — | Initial content. Uncontrolled — see the note below. | | onChange | (json, editor) => void | — | Called every time the document changes. | | onReady | (editor) => void | — | Called once, when the editor has finished initialising. | | editable | boolean | true | false for read-only; can be changed at runtime. | | uploadImage | (file, onProgress?, signal?) => Promise<string> | — | Uploads an image to your server, returns its URL. | | maxImageSize | number | 1048576 | Image size limit, in bytes. | | uploadAttachment | (file, onProgress?, signal?) => Promise<string \| { src?, fileId? }> | — | Uploads an attachment. Return src if your storage hands out stable URLs, or fileId if it is private and only issues short-lived ones. | | maxAttachmentSize | number | 26214400 | Attachment size limit, in bytes. | | onOpenAttachment | (attachment) => void | — | Opens an attachment that only has a fileId. Attachments with a src use a real <a> tag and never reach this. | | mentionSource | (query) => MentionItem[] \| Promise<MentionItem[]> | — | Leave it out to disable @mention entirely. | | locale | "vi" \| "en" | "vi" | Language of the editor's own labels. | | placeholder | string \| (({ editor, node }) => string) | — | Placeholder for an empty document. Empty headings always show Heading N; other empty nodes show nothing. Pass a function to decide entirely on your own. | | showToc | boolean | true | Table of contents in the right margin. | | tocVariant | "content" \| "line" | "line" | How the table of contents is rendered. | | onReplaceImage | () => void | — | Handles the "Replace" button in the image bubble menu. | | extensions | AnyExtension[] | [] | Extra Tiptap extensions. | | className / editorClassName | string | — | Classes for the outer frame / the editable area. | | ref | Ref<NotionEditorHandle> | — | Access to editor, getJSON, getHTML, setContent, focus. |

Attachments

The package knows nothing about your storage. It calls uploadAttachment, keeps whatever that function returns, and when the user clicks to download it either uses src directly or calls onOpenAttachment so the host app can fetch the content itself.

<NotionEditor
  uploadAttachment={async (file) => {
    const { fileId } = await uploadToPrivateStorage(file);
    // Private storage only issues short-lived URLs; embedding one in the
    // content guarantees it breaks a few minutes later — so store the id and
    // exchange it for a URL when it is actually needed.
    return { fileId };
  }}
  onOpenAttachment={async ({ fileId, name }) => {
    const blob = await fetchFromPrivateStorage(fileId);
    saveAs(blob, name);
  }}
/>

collectFileUrls(doc) returns every file URL a document references, base64 images excluded — useful when the host app needs to clean up storage after deleting a page.

content is not a controlled prop

Changing content does not reload the document. To switch to a different document, remount with key as shown above — that is cheaper than diffing the node tree, and it avoids the cursor jumping back to the top every time a parent re-renders mid-typing. For a deliberate overwrite, use ref.current.setContent(...).

Image upload

Without uploadImage, the upload block reports an error when the user picks a file, and dragged-in images fall back to inline base64. Base64 bloats a document very quickly, so do not let that fallback reach the content you persist.

Development

pnpm install
pnpm build       # -> lib/
pnpm type-check

Trying it in a host app before publishing

Use a tarball, not link: or pnpm link:

pnpm build && pnpm pack                                          # in this repo
pnpm add file:../notion-editor/tiptap-notion-editor-0.6.0.tgz    # in the host app

link: points outside the app's node_modules tree, so the package still loads react and prosemirror-* from its own. Two ProseMirror copies keep two separate PluginKey counters, both produce the key plugin$, and ProseMirror throws RangeError: Adding different instances of a keyed plugin the moment the editor view is created. Vite's resolve.dedupe cannot save you here, because Vitest treats a package outside the root directory as external and lets Node resolve it.

Installing from a tarball puts the package in the app's own store, and peer dependencies resolve to a single copy — exactly like installing from npm.

Publishing

pnpm type-check
npm version minor        # creates the version commit and tag
npm publish              # prepublishOnly runs the build
git push --follow-tags