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