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, // ⚠️ CRITICAL for SSR/Next.js
    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 setup
• templates/common-extensions.ts - Extension bundle
• templates/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({
      // Customize built-in extensions
      heading: {
        levels: [1, 2, 3],
      },
      bulletList: {
        keepMarks: true,
      },
    }),
    Image.configure({
      inline: true,
      allowBase64: false, // ⚠️ Prevent base64 bloat
      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, // Smart quotes, dashes, etc.
  ],
})

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> {
  // 1. Create base64 preview for immediate display
  const reader = new FileReader()
  const base64 = await new Promise<string>((resolve) => {
    reader.onload = () => resolve(reader.result as string)
    reader.readAsDataURL(file)
  })

  // 2. Insert preview into editor
  editor.chain().focus().setImage({ src: base64 }).run()

  // 3. Upload to R2 in background
  const formData = new FormData()
  formData.append('file', file)

  const response = await fetch('/api/upload', {
    method: 'POST',
    body: formData,
  })

  const { url } = await response.json()

  // 4. Replace base64 with permanent URL
  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