tiptap

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

• Setup and Configuration
• Extensions Catalog
• Image Upload
• Patterns
• Known Issues and Errors
• Prose Styling