Tiptap Rich Text Editor
Status: Production Ready
Last Updated: 2026-01-21
Dependencies: React 19+, Tailwind v4, shadcn/ui (recommended)
Latest Versions: @tiptap/[email protected], @tiptap/[email protected], @tiptap/[email protected] (verified 2026-01-21)
Quick Start (5 Minutes)
1. Install Dependencies
npm install @tiptap/react @tiptap/starter-kit @tiptap/pm @tiptap/extension-image @tiptap/extension-color @tiptap/extension-text-style @tiptap/extension-typography
Why this matters:
@tiptap/pm is required peer dependency (ProseMirror engine)- StarterKit bundles 20+ essential extensions (headings, lists, bold, italic, etc.)
- Image/color/typography are common additions not in StarterKit
Important: If using Tiptap v3.14.0+, drag handle functionality requires minimum v3.14.0 (regression fixed in that release). For Pro extensions with drag handles, React 18 is recommended due to tippyjs-react dependency.
2. Create SSR-Safe Editor
import { useEditor, EditorContent } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'
export function Editor() {
const editor = useEditor({
extensions: [StarterKit],
content: '<p>Hello World!</p>',
immediatelyRender: false,
editorProps: {
attributes: {
class: 'prose prose-sm focus:outline-none min-h-[200px] p-4',
},
},
})
return <EditorContent editor={editor} />
}
CRITICAL:
- Always set
immediatelyRender: false for Next.js/SSR apps (prevents hydration mismatch)
- Without this, you'll see: "SSR has been detected, please set
immediatelyRender explicitly to false"
- This is the #1 error reported by Tiptap users
3. Add Tailwind Typography (Optional but Recommended)
npm install @tailwindcss/typography
Update your tailwind.config.ts:
import typography from '@tailwindcss/typography'
export default {
plugins: [typography],
}
Why this matters:
- Provides default prose styling for headings, lists, links, etc.
- Without it, formatted content looks unstyled
- Alternative: Use custom Tailwind classes with
.tiptap selector
The 3-Step Setup Process
Step 1: Choose Your Integration Method
Option A: shadcn Minimal Tiptap Component (Recommended)
Install the pre-built shadcn component:
npx shadcn@latest add https://raw.githubusercontent.com/Aslam97/shadcn-minimal-tiptap/main/registry/block-registry.json
This installs:
- Fully-featured editor component with toolbar
- Image upload support
- Code block with syntax highlighting
- Typography extension configured
- Dark mode support
Option B: Build Custom Editor (Full Control)
Use templates from this skill:
templates/base-editor.tsx - Minimal editor setuptemplates/common-extensions.ts - Extension bundletemplates/tiptap-prose.css - Tailwind styling
Key Points:
- Option A: Faster setup, opinionated UI
- Option B: Complete customization, headless approach
- Both work with React + Tailwind v4
Step 2: Configure Extensions
Extensions add functionality to your editor:
import StarterKit from '@tiptap/starter-kit'
import Image from '@tiptap/extension-image'
import Link from '@tiptap/extension-link'
import Typography from '@tiptap/extension-typography'
const editor = useEditor({
extensions: [
StarterKit.configure({
heading: {
levels: [1, 2, 3],
},
bulletList: {
keepMarks: true,
},
}),
Image.configure({
inline: true,
allowBase64: false,
resize: {
enabled: true,
directions: ['top-right', 'bottom-right', 'bottom-left', 'top-left'],
minWidth: 100,
minHeight: 100,
alwaysPreserveAspectRatio: true,
},
}),
Link.configure({
openOnClick: false,
HTMLAttributes: {
class: 'text-primary underline',
},
}),
Typography,
],
})
CRITICAL:
- Set
allowBase64: false to prevent huge JSON payloads
- Use upload handler pattern (see templates/image-upload-r2.tsx)
- Extension order matters - dependencies must load first
Step 3: Handle Image Uploads (If Needed)
Pattern: Base64 preview → background upload → replace with URL
See templates/image-upload-r2.tsx for full implementation:
import { Editor } from '@tiptap/core'
async function uploadImageToR2(file: File, env: Env): Promise<string> {
const reader = new FileReader()
const base64 = await new Promise<string>((resolve) => {
reader.onload = () => resolve(reader.result as string)
reader.readAsDataURL(file)
})
editor.chain().focus().setImage({ src: base64 }).run()
const formData = new FormData()
formData.append('file', file)
const response = await fetch('/api/upload', {
method: 'POST',
body: formData,
})
const { url } = await response.json()
editor.chain()
.focus()
.updateAttributes('image', { src: url })
.run()
return url
}
Why this pattern:
- Immediate user feedback (preview)
- No database bloat from base64
- Works with Cloudflare R2
- Graceful error handling
Critical Rules
Always Do
✅ Set immediatelyRender: false in useEditor() for SSR apps
✅ Install @tailwindcss/typography for prose styling
✅ Use upload handler for images (not base64)
✅ Memoize editor configuration to prevent re-renders
✅ Include @tiptap/pm peer dependency
Never Do
❌ Use immediatelyRender: true (default) with Next.js/SSR
❌ Store images as base64 in database (use URL after upload)
❌ Forget to add prose classes to editor container
❌ Load more than 100 widgets in collaborative mode
❌ Use Create React App (v3 incompatible - use Vite)
Known Issues Prevention
This skill prevents 7 documented issues:
Issue #1: SSR Hydration Mismatch
Error: "SSR has been detected, please set immediatelyRender explicitly to false"
Source: GitHub Issue #5856, #5602
Why It Happens: Default immediatelyRender: true breaks Next.js hydration
Prevention: Template includes immediatelyRender: false by default
Issue #2: Editor Re-renders on Every Keystroke
Error: Laggy typing, poor performance in large documents
Source: Tiptap Performance Docs
Why It Happens: useEditor() hook re-renders component on every change
Prevention: Use useEditorState() hook or memoization patterns (see templates)
Issue #3: Tailwind Typography Not Working
Error: Headings/lists render unstyled, no formatting visible
Source: shadcn Tiptap Discussion
Why It Happens: Missing @tailwindcss/typography plugin
Prevention: Skill includes typography plugin installation in checklist
Issue #4: Image Upload Base64 Bloat
Error: JSON payloads beco
