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
References