Back to Details

tiptap

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Tiptap Rich Text Editor

Tiptap 富文本编辑器

Overview

概述

Tiptap 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).
Tiptap是基于ProseMirror构建的无头富文本编辑器，为React应用提供模块化扩展系统。它支持React 19、Tailwind v4以及Next.js等SSR框架。适用于构建博客编辑器、评论系统、文档工具或类Notion的协同应用。请勿与Create React App（CRA）配合使用（CRA与Tiptap v3的ESM模块结构不兼容，请改用Vite）。

Quick Reference

快速参考

PatternAPI / Key Point
Create editor
useEditor({ extensions: [StarterKit], immediatelyRender: false })
Render editor
<EditorContent editor={editor} />
Prose stylingAdd 
className="prose dark:prose-invert max-w-none"
to container
Configure StarterKit
StarterKit.configure({ heading: { levels: [1, 2, 3] } })
Disable undo/redo
StarterKit.configure({ undoRedo: false })
(required for Y.js collab)
Image uploadSet 
allowBase64: false
, use upload handler with URL replacement
Markdown support
import { Markdown } from '@tiptap/markdown'
(official, open-source)
shadcn component
npx shadcn@latest add https://raw.githubusercontent.com/Aslam97/shadcn-minimal-tiptap/main/registry/block-registry.json
Null guard
useEditor()
returns 
Editor | null
— guard before calling methods
模式API / 关键点
创建编辑器
useEditor({ extensions: [StarterKit], immediatelyRender: false })
渲染编辑器
<EditorContent editor={editor} />
文档样式为容器添加 
className="prose dark:prose-invert max-w-none"
配置StarterKit
StarterKit.configure({ heading: { levels: [1, 2, 3] } })
禁用撤销/重做
StarterKit.configure({ undoRedo: false })
（使用Y.js协同编辑时必需）
图片上传设置 
allowBase64: false
，使用上传处理器替换URL
Markdown支持
import { Markdown } from '@tiptap/markdown'
（官方开源）
shadcn组件
npx shadcn@latest add https://raw.githubusercontent.com/Aslam97/shadcn-minimal-tiptap/main/registry/block-registry.json
空值校验
useEditor()
返回 
Editor | null
— 调用方法前需进行校验

Core Dependencies

核心依赖

PackagePurpose
@tiptap/react
React integration (React 19 supported since v2.10.0)
@tiptap/starter-kit
Bundled extensions: marks, nodes, and functionality
@tiptap/pm
ProseMirror peer dependency (required, not auto-installed)
@tailwindcss/typography
Prose styling for headings, lists, links
包用途
@tiptap/react
React集成（v2.10.0起支持React 19）
@tiptap/starter-kit
捆绑扩展：标记、节点及功能
@tiptap/pm
ProseMirror对等依赖（必需，不会自动安装）
@tailwindcss/typography
为标题、列表、链接提供文档样式

StarterKit v3 Contents

StarterKit v3 包含内容

CategoryIncluded
MarksBold, Italic, Strike, Code, Link (v3), Underline (v3)
NodesDocument, Paragraph, Text, Heading, BulletList, OrderedList, ListItem, Blockquote, CodeBlock, HorizontalRule, HardBreak
FunctionalityUndo/Redo, Dropcursor, Gapcursor, ListKeymap (v3), TrailingNode (v3)
分类包含内容
标记Bold、Italic、Strike、Code、Link（v3）、Underline（v3）
节点Document、Paragraph、Text、Heading、BulletList、OrderedList、ListItem、Blockquote、CodeBlock、HorizontalRule、HardBreak
功能Undo/Redo、Dropcursor、Gapcursor、ListKeymap（v3）、TrailingNode（v3）

Common Additional Extensions

常用附加扩展

ExtensionPackageUse Case
Image
@tiptap/extension-image
Image support with resize
Color
@tiptap/extension-color
Text color (requires TextStyle)
Typography
@tiptap/extension-typography
Smart quotes, dashes, ellipsis
Placeholder
@tiptap/extension-placeholder
Placeholder text (requires CSS)
Table
@tiptap/extension-table
Table support (+ Row, Cell, Header)
TaskList
@tiptap/extension-task-list
Checkbox task lists
CodeBlockLowlight
@tiptap/extension-code-block-lowlight
Syntax-highlighted code
Collaboration
@tiptap/extension-collaboration
Real-time multi-user editing (Y.js)
Markdown
@tiptap/markdown
Bidirectional markdown (open-source)
扩展包适用场景
Image
@tiptap/extension-image
支持缩放的图片功能
Color
@tiptap/extension-color
文本颜色（需要TextStyle扩展）
Typography
@tiptap/extension-typography
智能引号、破折号、省略号
Placeholder
@tiptap/extension-placeholder
占位符文本（需要CSS支持）
Table
@tiptap/extension-table
表格支持（+行、单元格、表头）
TaskList
@tiptap/extension-task-list
复选框任务列表
CodeBlockLowlight
@tiptap/extension-code-block-lowlight
带语法高亮的代码块
Collaboration
@tiptap/extension-collaboration
实时多用户编辑（Y.js）
Markdown
@tiptap/markdown
双向Markdown支持（开源）

Common Mistakes

常见错误

MistakeFix
Missing 
immediatelyRender: false
Add to 
useEditor()
config — required for SSR/Next.js
No 
prose
classes on editor container		Add 
className="prose prose-sm dark:prose-invert max-w-none"
Images stored as base64Set 
allowBase64: false
, use upload handler with URL replacement
Using EditorProvider + useEditor togetherChoose one — EditorProvider wraps useEditor internally
Undo/Redo enabled with CollaborationSet 
undoRedo: false
in StarterKit when using Y.js
ProseMirror version conflictsAdd 
resolutions
for prosemirror-model/view/state in package.json
Using Create React AppSwitch to Vite — CRA incompatible with v3 ESM modules
Not checking 
editor
for null
useEditor()
returns 
Editor | null
— guard before use
Using 
history: false
for collab		Config key renamed to 
undoRedo
in v3
Importing 
@tiptap/extension-markdown
Correct package is 
@tiptap/markdown
错误修复方案
缺少 
immediatelyRender: false
在
useEditor()
配置中添加该参数 — SSR/Next.js必需
编辑器容器未添加
prose
类		添加 
className="prose prose-sm dark:prose-invert max-w-none"
图片以base64格式存储设置
allowBase64: false
，使用上传处理器替换URL
同时使用EditorProvider和useEditor二选一 — EditorProvider内部已封装useEditor
协同编辑时启用了撤销/重做使用Y.js时，在StarterKit中设置
undoRedo: false
ProseMirror版本冲突在package.json中为prosemirror-model/view/state添加
resolutions
配置
使用Create React App切换到Vite — CRA与v3 ESM模块不兼容
未检查
editor
是否为null
useEditor()
返回
Editor | null
— 使用前需校验
为协同编辑设置
history: false
v3中配置项已重命名为
undoRedo
导入
@tiptap/extension-markdown
正确的包是
@tiptap/markdown

Delegation

相关参考

  • Tailwind styling: see 
    tailwind
    skill
  • Form integration: see 
    tanstack-form
    skill
  • Tailwind样式：参考
    tailwind
    技能文档
  • 表单集成：参考
    tanstack-form
    技能文档

References

参考链接

  • Setup and Configuration
  • Extensions Catalog
  • Image Upload
  • Patterns
  • Known Issues and Errors
  • Prose Styling
  • 配置与设置
  • 扩展目录
  • 图片上传
  • 设计模式
  • 已知问题与错误
  • 文档样式