/web-editor-tiptap

name: web-editor-tiptap
description: Rich text editor framework with TipTap and ProseMirror

TipTap Editor Patterns

> **Quick Guide:** TipTap is a headless, framework-agnostic rich text editor built on ProseMirror. Everything is an extension -- nodes define block/inline content, marks define formatting, extensions add functionality. Use `useEditor` hook (React/Vue) or the `Editor` class directly. Prefer JSON serialization over HTML. Set `immediatelyRender: false` for SSR. **Current: v3.x** -- Floating UI replaces Tippy.js, menus import from `/menus` sub-path, StarterKit includes Link/Underline by default.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST set `immediatelyRender: false` in useEditor when using SSR/SSG frameworks -- TipTap must never render on the server)**

**(You MUST import BubbleMenu and FloatingMenu from the `/menus` sub-path -- e.g. `@tiptap/react/menus` in v3)**

**(You MUST define `name`, `group`, `parseHTML`, and `renderHTML` on every custom Node -- missing any breaks schema resolution)**

**(You MUST use `editor.chain().focus()...run()` for chained commands -- forgetting `.focus()` loses cursor position, forgetting `.run()` silently does nothing)**

</critical_requirements>

---

**Auto-detection:** TipTap, tiptap, @tiptap/core, @tiptap/react, @tiptap/vue-3, @tiptap/starter-kit, useEditor, EditorContent, BubbleMenu, FloatingMenu, Node.create, Mark.create, Extension.create, NodeViewWrapper, NodeViewContent, ReactNodeViewRenderer, ProseMirror, editor.chain, editor.commands, addKeyboardShortcuts, addInputRules, addNodeView

**When to use:**

• Building rich text editors with custom formatting and block types
• Creating WYSIWYG editors with toolbar, bubble menu, or floating menu UIs
• Implementing custom nodes (embeds, mentions, code blocks with syntax highlighting)
• Serializing editor content to JSON or HTML for persistence
• Adding keyboard shortcuts, input rules, or paste rules to an editor

**When NOT to use:**

• Plain text input or textarea (use native HTML elements)
• Markdown-only editors without rich text rendering (use a markdown parser)
• Read-only content display (use a static renderer or HTML)

**Key patterns covered:**

• Editor setup with useEditor hook and EditorContent component
• Extension architecture: Node, Mark, and Extension types
• Custom node and mark creation with schema, commands, and keyboard shortcuts
• BubbleMenu and FloatingMenu for contextual toolbars
• React node views for complex interactive blocks
• Content serialization (JSON preferred) and persistence
• Input rules and paste rules for automatic formatting

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Editor setup, extensions, serialization, toolbar
• [examples/custom-extensions.md](examples/custom-extensions.md) - Custom nodes, marks, input rules, keyboard shortcuts
• [examples/menus.md](examples/menus.md) - BubbleMenu, FloatingMenu, slash commands
• [reference.md](reference.md) - Decision frameworks, StarterKit contents, anti-patterns

---

<philosophy>

Philosophy

TipTap is a **headless editor framework** -- it provides behavior, schema, and state management without imposing any UI. You build the UI (toolbars, menus, formatting controls) yourself using your preferred component framework and styling solution.

**Everything is an extension.** Even core features like paragraphs, bold text, and undo/redo are extensions. This means:

1. **You control the schema** -- only include what your editor needs 2. **Extensions are composable** -- combine, configure, or extend any extension 3. **Custom content types are first-class** -- creating a custom node is the same API as built-in nodes

**ProseMirror under the hood.** TipTap wraps ProseMirror, so you get its battle-tested schema system, transaction model, and plugin architecture. When TipTap's API isn't enough, drop down to ProseMirror directly via `addProseMirrorPlugins()`.

**Framework-agnostic core.** `@tiptap/core` works with vanilla JS. Framework adapters (`@tiptap/react`, `@tiptap/vue-3`) add hooks and components but the editor logic is shared.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Editor Setup

The `useEditor` hook initializes the editor with extensions and content. `EditorContent` renders the editable area.

import { useEditor, EditorContent } from "@tiptap/react";
import StarterKit from "@tiptap/starter-kit";

const INITIAL_CONTENT = "<p>Start typing...</p>";

function RichTextEditor() {
  const editor = useEditor({
    extensions: [StarterKit],
    content: INITIAL_CONTENT,
    immediatelyRender: false, // Required for SSR frameworks
  });

  return <EditorContent editor={editor} />;
}

**Why good:** StarterKit bundles common extensions (paragraphs, headings, lists, bold, italic, etc.), `immediatelyRender: false` prevents SSR hydration mismatch

**Key useEditor options:** `extensions` (required), `content` (HTML string or JSON), `editable`, `autofocus` (`"start"`, `"end"`, `"all"`, number, boolean), `editorProps` (ProseMirror props like `attributes` for CSS classes), `onUpdate` callback

See [examples/core.md](examples/core.md) for full setup with toolbar and configuration options.

---

Pattern 2: Extension Types

TipTap has three extension types that map to ProseMirror's schema model:

| Type | Purpose | Examples | |------|---------|---------| | **Node** | Content blocks and inline elements | Paragraph, Heading, Image, CodeBlock, Table | | **Mark** | Formatting applied to text ranges | Bold, Italic, Link, Highlight, Code | | **Extension** | Functionality without schema changes | UndoRedo, CharacterCount, Placeholder, Focus |

import { Node } from "@tiptap/core";
import { Mark } from "@tiptap/core";
import { Extension } from "@tiptap/core";

// Each type uses the