Tiptap Rich Text Editor

Overview

Tiptap is a headless rich text editor built on ProseMirror, providing a modular extension system for React applications. It supports React 19, Tailwind v4, and SSR frameworks like Next.js. Use when building blog editors, comment systems, documentation tools, or Notion-like collaborative apps. Do NOT use with Create React App (CRA is incompatible with Tiptap v3 ESM module structure; use Vite instead).

Quick Reference

Pattern	API / Key Point
Create editor	`useEditor({ extensions: [StarterKit], immediatelyRender: false })`
Render editor	`<EditorContent editor={editor} />`
Prose styling	Add `className="prose dark:prose-invert max-w-none"` to container
Configure StarterKit	`StarterKit.configure({ heading: { levels: [1, 2, 3] } })`
Disable undo/redo	`StarterKit.configure({ undoRedo: false })` (required for Y.js collab)
Image upload	Set `allowBase64: false`, use upload handler with URL replacement
Markdown support	`import { Markdown } from '@tiptap/markdown'` (official, open-source)
shadcn component	`npx shadcn@latest add https://raw.githubusercontent.com/Aslam97/shadcn-minimal-tiptap/main/registry/block-registry.json`
Null guard	`useEditor()` returns `Editor \| null` — guard before calling methods

Core Dependencies

Package	Purpose
`@tiptap/react`	React integration (React 19 supported since v2.10.0)
`@tiptap/starter-kit`	Bundled extensions: marks, nodes, and functionality
`@tiptap/pm`	ProseMirror peer dependency (required, not auto-installed)
`@tailwindcss/typography`	Prose styling for headings, lists, links

StarterKit v3 Contents

Category	Included
Marks	Bold, Italic, Strike, Code, Link (v3), Underline (v3)
Nodes	Document, Paragraph, Text, Heading, BulletList, OrderedList, ListItem, Blockquote, CodeBlock, HorizontalRule, HardBreak
Functionality	Undo/Redo, Dropcursor, Gapcursor, ListKeymap (v3), TrailingNode (v3)

Common Additional Extensions

Extension	Package	Use Case
Image	`@tiptap/extension-image`	Image support with resize
Color	`@tiptap/extension-color`	Text color (requires TextStyle)
Typography	`@tiptap/extension-typography`	Smart quotes, dashes, ellipsis
Placeholder	`@tiptap/extension-placeholder`	Placeholder text (requires CSS)
Table	`@tiptap/extension-table`	Table support (+ Row, Cell, Header)
TaskList	`@tiptap/extension-task-list`	Checkbox task lists
CodeBlockLowlight	`@tiptap/extension-code-block-lowlight`	Syntax-highlighted code
Collaboration	`@tiptap/extension-collaboration`	Real-time multi-user editing (Y.js)
Markdown	`@tiptap/markdown`	Bidirectional markdown (open-source)

Common Mistakes

Mistake	Fix
Missing `immediatelyRender: false`	Add to `useEditor()` config — required for SSR/Next.js
No `prose` classes on editor container	Add `className="prose prose-sm dark:prose-invert max-w-none"`
Images stored as base64	Set `allowBase64: false`, use upload handler with URL replacement
Using EditorProvider + useEditor together	Choose one — EditorProvider wraps useEditor internally
Undo/Redo enabled with Collaboration	Set `undoRedo: false` in StarterKit when using Y.js
ProseMirror version conflicts	Add `resolutions` for prosemirror-model/view/state in package.json
Using Create React App	Switch to Vite — CRA incompatible with v3 ESM modules
Not checking `editor` for null	`useEditor()` returns `Editor \| null` — guard before use
Using `history: false` for collab	Config key renamed to `undoRedo` in v3
Importing `@tiptap/extension-markdown`	Correct package is `@tiptap/markdown`

Delegation

Tailwind styling: see tailwind skill
Form integration: see tanstack-form skill

tiptap