tiptap

intent

tiptap is a headless react rich text editor built on prosemirror. use it when you need inline editing with formatting (bold, italic, lists, headings, links, images), collaborative features, or markdown support. works with next.js/ssr, tailwind v4, and shadcn/ui. this skill prevents 7 common setup pitfalls and handles image uploads, ssr hydration, and extension conflicts.

inputs

required dependencies:

• react 18+ (react 19 supported as of v2.10.0, some pro extensions need react 18 due to archived tippyjs-react)
• @tiptap/react@3.16.0+
• @tiptap/starter-kit@3.16.0+ (bundles 20+ extensions: headings, lists, bold, italic, code blocks, etc.)
• @tiptap/pm@3.16.0+ (prosemirror peer dependency, prevents version conflicts)
• tailwind v4
• tailwindcss/typography plugin (optional but strongly recommended for prose styling)

optional dependencies (add as needed):

• @tiptap/extension-image@3.16.0+ (image support)
• @tiptap/extension-link@3.16.0+ (link support, included in starter-kit)
• @tiptap/extension-color@3.16.0+ (text color)
• @tiptap/extension-typography@3.16.0+ (smart quotes, dashes)
• @tiptap/extension-collaboration@3.16.0+ (y.js real-time collab)
• @tiptap/extension-markdown@3.16.0+ (markdown parsing and output, beta)
• @tiptap/extension-audio@3.16.0+ (audio embeds, new in v3.16.0)
• yjs@13.6.0+ (collaborative editing backend)
• react-medium-image-zoom@5.2.0+ (image zoom)

external connections (if using image uploads):

• cloudflare r2 or s3 compatible storage (api endpoint, access key id, secret access key)
• set up env vars: NEXT_PUBLIC_R2_ENDPOINT, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY (or equivalent for your host)

context (if building custom):

• tailwind config file (tailwind.config.ts or tailwind.config.js)
• react component file (.tsx or .jsx)
• if using next.js: app router or pages router (affects ssr config)

procedure

step 1: install dependencies

run:

npm install @tiptap/react@3.16.0 @tiptap/starter-kit@3.16.0 @tiptap/pm@3.16.0 @tiptap/extension-image@3.16.0 @tiptap/extension-color@3.16.0 @tiptap/extension-text-style@3.16.0 @tiptap/extension-typography@3.16.0 @tailwindcss/typography@0.5.19

input: package.json, npm or yarn output: node_modules updated with tiptap packages, package.json.lock updated

why each package:

• @tiptap/pm: required peer dependency for prosemirror engine (if missing, multiple prosemirror versions conflict)
• starter-kit: bundles essential extensions (don't install individual heading/list/bold extensions, they're redundant)
• image/color/typography: common additions not in starter-kit
• @tailwindcss/typography: required for prose class support (headings, lists, code blocks look styled)

step 2: configure tailwind prose plugin

input: tailwind.config.ts (or .js)

edit tailwind.config.ts:

import typography from '@tailwindcss/typography'

export default {
  plugins: [typography],
  // ...rest of config
}

output: tailwind config updated with typography plugin

critical: without this plugin, formatted content (headings, lists, etc.) renders unstyled. alternatives exist (custom .tiptap css classes) but prose is fastest.

step 3: create base editor component

input: react component file (.tsx)

create file (e.g., Editor.tsx):

import { useEditor, EditorContent } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'
import Typography from '@tiptap/extension-typography'

export function Editor() {
  const editor = useEditor({
    extensions: [
      StarterKit,
      Typography,
    ],
    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 dark:prose-invert',
      },
    },
  })

  return <EditorContent editor={editor} />
}

output: functional react editor component

critical settings:

• immediatelyRender: false: prevents "SSR has been detected" error in next.js. set to true only if you're not using ssr.
• prose prose-sm prose-invert: applies tailwind typography styling. without these classes, formatting is invisible.
• extensions: load in dependency order (starter-kit before custom extensions).

step 4: configure extensions (if using images, links, or custom formatting)

input: editor component from step 3, file storage credentials (if uploading images)

update editor config:

import { useEditor, EditorContent } from '@tiptap/react'
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, // CRITICAL: prevents json 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,
  ],
  immediatelyRender: false,
  content: '<p>Hello World!</p>',
})

output: editor with image, link, and typography support configured

critical settings:

• allowBase64: false: prevents storing images as base64, which bloats json payloads (can turn 50kb to 5mb). always use url-based uploads instead.
• extension order: dependencies must load before dependents (e.g., image before link if link references images).
• starter-kit.configure(): customize which heading levels, whether to keep marks on list items, etc.

step 5: add image upload handler (if using images)

input: editor component with image extension, r2/s3 credentials in env vars, api route handler

create api route (e.g., pages/api/upload.ts or app/api/upload/route.ts):

// app/api/upload/route.ts (Next.js app router)
export async function POST(request: Request) {
  const formData = await request.formData()
  const file = formData.get('file') as File

  if (!file) {
    return Response.json({ error: 'no file' }, { status: 400 })
  }

  const arrayBuffer = await file.arrayBuffer()
  const buffer = Buffer.from(arrayBuffer)
  const filename = `${Date.now()}-${file.name}`

  // upload to r2 (or s3)
  const s3 = new AWS.S3({
    endpoint: process.env.R2_ENDPOINT,
    accessKeyId: process.env.R2_ACCESS_KEY_ID,
    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
    region: 'auto',
  })

  try {
    await s3.putObject({
      Bucket: process.env.R2_BUCKET!,
      Key: filename,
      Body: buffer,
      ContentType: file.type,
    }).promise()

    const url = `${process.env.R2_PUBLIC_URL}/${filename}`
    return Response.json({ url }, { status: 200 })
  } catch (error) {
    console.error(error)
    return Response.json({ error: 'upload failed' }, { status: 500 })
  }
}

update editor component to handle uploads:

const editor = useEditor({
  extensions: [
    Image.configure({
      inline: true,
      allowBase64: false,
      upload: {
        handler: async (file: File) => {
          // 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/s3 in background
          const formData = new FormData()
          formData.append('file', file)

          try {
            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
          } catch (error) {
            console.error('image upload failed:', error)
            // leave base64 in place as fallback
            return base64
          }
        },
      },
    }),
  ],
  immediatelyRender: false,
})

input: file dropped/selected in editor, api endpoint running, r2/s3 credentials in env output: image url stored in editor, image rendered immediately via base64, then replaced with permanent url after upload completes

why this pattern:

• immediate user feedback (base64 preview shows instantly)
• no database bloat (urls only, not multi-megabyte base64 strings)
• works offline briefly (preview persists until upload finishes)
• graceful degradation (if upload fails, base64 fallback)

step 6: integrate into forms (optional, if using react-hook-form or similar)

input: react-hook-form controller, editor component

import { useForm, Controller } from 'react-hook-form'
import { Editor } from './Editor'

function BlogForm() {
  const { control, handleSubmit } = useForm({
    defaultValues: { content: '<p></p>' },
  })

  return (
    <form onSubmit={handleSubmit((data) => console.log(data))}>
      <Controller
        name="content"
        control={control}
        rules={{ required: 'content required' }}
        render={({ field }) => (
          <Editor
            defaultValue={field.value}
            onChange={(html) => field.onChange(html)}
          />
        )}
      />
      <button type="submit">Save</button>
    </form>
  )
}

update Editor.tsx to accept props:

export function Editor({ defaultValue = '<p></p>', onChange }: {
  defaultValue?: string
  onChange?: (html: string) => void
}) {
  const editor = useEditor({
    extensions: [StarterKit, Typography],
    content: defaultValue,
    immediatelyRender: false,
    editorProps: {
      attributes: {
        class: 'prose prose-sm focus:outline-none min-h-[200px] p-4 dark:prose-invert',
      },
    },
    onUpdate: ({ editor }) => {
      onChange?.(editor.getHTML())
    },
  })

  return <EditorContent editor={editor} />
}

input: form data, editor component with onChange callback output: editor value synced to form state, ready for submission

step 7: optional - add markdown support (if storing/editing markdown instead of html)

input: editor component, markdown content string

install: npm install @tiptap/markdown@3.16.0

update editor:

import { Markdown } from '@tiptap/markdown'

const editor = useEditor({
  extensions: [StarterKit, Markdown],
  content: '# Hello World\n\nThis is **Markdown**!',
  contentType: 'markdown', // CRITICAL: must specify or html assumed
  immediatelyRender: false,
})

// get markdown output
const markdownOutput = editor.getMarkdown()

// set markdown content
editor.commands.setContent('## New heading', { contentType: 'markdown' })

input: markdown string output: editor renders markdown as rich text, getMarkdown() returns markdown string

critical: always specify contentType: 'markdown' when setting markdown content, or it will be parsed as html.

step 8: optional - add collaborative editing with y.js (if multi-user real-time editing needed)

input: editor component, y.js WebSocket provider or backend

install: npm install yjs @tiptap/extension-collaboration@3.16.0 y-websocket@0.3.2

import { useEditor } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'
import Collaboration from '@tiptap/extension-collaboration'
import * as Y from 'yjs'
import { WebsocketProvider } from 'y-websocket'

const ydoc = new Y.Doc()
const provider = new WebsocketProvider(
  'ws://localhost:1234',
  'shared-doc',
  ydoc
)

const editor = useEditor({
  extensions: [
    StarterKit.configure({
      history: false, // disable history, collab provides version control
    }),
    Collaboration.configure({
      document: ydoc,
    }),
  ],
  immediatelyRender: false,
})

input: websocket endpoint running y.js server, editor component output: editor synced across clients, all edits propagated in real-time

limits: do not load more than 100 concurrent widgets in collaborative mode (performance degradation).

step 9: verify setup with checklist

input: completed editor component, tailwind config, api routes (if images)

verification checklist:

• @tiptap/react, @tiptap/starter-kit, @tiptap/pm installed (run npm list @tiptap/react)
• immediatelyRender: false set in useEditor() config
• @tailwindcss/typography plugin added to tailwind.config.ts
• prose prose-sm dark:prose-invert classes applied to editor container
• if using images: allowBase64: false configured, upload handler defined, api route running
• if using create react app: switched to vite (cra incompatible with tiptap v3)
• dev server runs without "SSR has been detected" error
• formatted text displays correctly (bold, italic, headings, lists visible)
• no console errors about multiple prosemirror versions
• production build succeeds (npm run build)

output: green checklist, ready for development/production

decision points

if using next.js or any ssr framework:

• set immediatelyRender: false in useEditor() config
• else if client-side only (vite spa): can omit or set to true, but false is safer

if images needed:

• use upload handler pattern with base64 preview + url replacement
• else if no images: skip image extension entirely

if storing html in database:

• use editor.getHTML() to extract, store as string or json
• else if storing markdown: use editor.getMarkdown() and contentType: 'markdown'
• else if using collaborative editing: store y.js binary snapshot in database

if building quick setup:

• use npx shadcn@latest add (pre-built component with toolbar, image upload, syntax highlighting)
• else if need full control: build custom from templates/base-editor.tsx

if typing lags or performance poor:

• use useEditorState() hook for read-only text display
• else: memoize editor config to prevent re-renders on every keystroke
• else if using collab: reduce widget count below 100, upgrade server

if build fails in create react app:

• migrate to vite (cra incompatible with tiptap v3 module structure)
• else: use tiptap v2 (older, stable but missing new features)

if prosemirror conflicts appear ("multiple versions" error):

• add package.json resolutions to lock prosemirror versions
• else: reinstall node_modules (rm -rf node_modules package-lock.json && npm install)

if headings/lists unstyled:

• ensure @tailwindcss/typography installed and plugin added to config
• else: add custom .tiptap css classes (see references/tiptap-prose.css)

if using both editorprovider and useeditor:

• choose one: editorprovider for context setup, or useeditor for direct instance
• do not use both simultaneously (causes hydration mismatch)

if react 19 and drag handles needed:

• check tiptap pro extension compatibility (archived tippyjs-react may lack react 19 support)
• else: use react 18 or wait for tippyjs-react update

output contract

on success, you will have:

1. working editor component (React) that renders rich text with formatting (bold, italic, headings, lists, links, code blocks)