1---2name: tiptap3description: Builds rich text editors with Tiptap, a headless ProseMirror-based editor framework for React with Tailwind v4 support. Covers SSR-safe setup, image uploads, prose styling, collaborative editing, and markdown support. Use when adding a rich text editor, configuring Tiptap extensions, handling image uploads in editors, or setting up collaborative editing with Y.js. Use for tiptap, rich text, editor, prosemirror, react, tailwind.4license: MIT5---6
7# Tiptap Rich Text Editor
8
9## Overview
10
11Tiptap 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).
12
13## Quick Reference
14
15| Pattern | API / Key Point |
16| -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
17| Create editor | `useEditor({ extensions: [StarterKit], immediatelyRender: false })` |
18| Render editor | `<EditorContent editor={editor} />` |
19| Prose styling | Add `className="prose dark:prose-invert max-w-none"` to container |
20| Configure StarterKit | `StarterKit.configure({ heading: { levels: [1, 2, 3] } })` |
21| Disable undo/redo | `StarterKit.configure({ undoRedo: false })` (required for Y.js collab) |
22| Image upload | Set `allowBase64: false`, use upload handler with URL replacement |
23| Markdown support | `import { Markdown } from '@tiptap/markdown'` (official, open-source) |
24| shadcn component | `npx shadcn@latest add https://raw.githubusercontent.com/Aslam97/shadcn-minimal-tiptap/main/registry/block-registry.json` |
25| Null guard | `useEditor()` returns `Editor \| null` — guard before calling methods |
26
27## Core Dependencies
28
29| Package | Purpose |
30| ------------------------- | ---------------------------------------------------------- |
31| `@tiptap/react` | React integration (React 19 supported since v2.10.0) |
32| `@tiptap/starter-kit` | Bundled extensions: marks, nodes, and functionality |
33| `@tiptap/pm` | ProseMirror peer dependency (required, not auto-installed) |
34| `@tailwindcss/typography` | Prose styling for headings, lists, links |
35
36## StarterKit v3 Contents
37
38| Category | Included |
39| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
40| Marks | Bold, Italic, Strike, Code, Link (v3), Underline (v3) |
41| Nodes | Document, Paragraph, Text, Heading, BulletList, OrderedList, ListItem, Blockquote, CodeBlock, HorizontalRule, HardBreak |
42| Functionality | Undo/Redo, Dropcursor, Gapcursor, ListKeymap (v3), TrailingNode (v3) |
43
44## Common Additional Extensions
45
46| Extension | Package | Use Case |
47| ----------------- | --------------------------------------- | ------------------------------------ |
48| Image | `@tiptap/extension-image` | Image support with resize |
49| Color | `@tiptap/extension-color` | Text color (requires TextStyle) |
50| Typography | `@tiptap/extension-typography` | Smart quotes, dashes, ellipsis |
51| Placeholder | `@tiptap/extension-placeholder` | Placeholder text (requires CSS) |
52| Table | `@tiptap/extension-table` | Table support (+ Row, Cell, Header) |
53| TaskList | `@tiptap/extension-task-list` | Checkbox task lists |
54| CodeBlockLowlight | `@tiptap/extension-code-block-lowlight` | Syntax-highlighted code |
55| Collaboration | `@tiptap/extension-collaboration` | Real-time multi-user editing (Y.js) |
56| Markdown | `@tiptap/markdown` | Bidirectional markdown (open-source) |
57
58## Common Mistakes
59
60| Mistake | Fix |
61| ----------------------------------------- | ------------------------------------------------------------------ |
62| Missing `immediatelyRender: false` | Add to `useEditor()` config — required for SSR/Next.js |
63| No `prose` classes on editor container | Add `className="prose prose-sm dark:prose-invert max-w-none"` |
64| Images stored as base64 | Set `allowBase64: false`, use upload handler with URL replacement |
65| Using EditorProvider + useEditor together | Choose one — EditorProvider wraps useEditor internally |
66| Undo/Redo enabled with Collaboration | Set `undoRedo: false` in StarterKit when using Y.js |
67| ProseMirror version conflicts | Add `resolutions` for prosemirror-model/view/state in package.json |
68| Using Create React App | Switch to Vite — CRA incompatible with v3 ESM modules |
69| Not checking `editor` for null | `useEditor()` returns `Editor \| null` — guard before use |
70| Using `history: false` for collab | Config key renamed to `undoRedo` in v3 |
71| Importing `@tiptap/extension-markdown` | Correct package is `@tiptap/markdown` |
72
73## Delegation
74
75- **Tailwind styling**: see `tailwind` skill
76- **Form integration**: see `tanstack-form` skill
77
78## References
79
80- [Setup and Configuration](references/setup.md)
81- [Extensions Catalog](references/extensions.md)
82- [Image Upload](references/image-upload.md)
83- [Patterns](references/patterns.md)
84- [Known Issues and Errors](references/known-issues.md)
85- [Prose Styling](references/prose-styling.md)
oakoss