Hello world!
- Item 1
- Item 2
Hello World!
', }) [](https://tiptap.dev/docs/guides/migrate-from-ckeditor4#extensions) Extensions ------------------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/migrate-from-ckeditor4#understanding-tiptaps-extension-system) Understanding Tiptap's extension system Tiptap uses a modular extension system that replaces CKEditor 4's plugin architecture. Each feature is an independent extension that can be configured and customized. The [StarterKit](https://tiptap.dev/docs/editor/extensions/functionality/starterkit) is a bundle of all the basic extensions, and you can add or remove other extensions as needed. Explore all available extensions in our [extensions guide](https://tiptap.dev/docs/editor/extensions/overview) , or [create your own](https://tiptap.dev/docs/editor/extensions/custom-extensions) to support custom functionality and HTML elements. ### [](https://tiptap.dev/docs/guides/migrate-from-ckeditor4#common-ckeditor-4-plugin-equivalents) Common CKEditor 4 plugin equivalents | CKEditor 4 Plugin | Tiptap Extension | Notes | | --- | --- | --- | | `basicstyles` | `Bold`, `Italic`, `Underline` | Included in StarterKit | | `list` | `BulletList`, `OrderedList`, `ListItem` | Included in StarterKit | | `link` | `Link` | Included in StarterKit | | `image` | `Image` | Available separately | | `table` | `Table` | Available separately | | `sourcearea` | `CodeBlock` | Included in StarterKit | | `format` | `Heading` | Included in StarterKit | | `blockquote` | `Blockquote` | Included in StarterKit | | `justify` | `TextAlign` | Available separately | | `colorbutton` | `TextStyle`, `Color` | Available separately | | `font` | `TextStyle`, `FontSize` | Available separately | | `indentlist` | Built into list extensions | Included in StarterKit | | `horizontalrule` | `HorizontalRule` | Included in StarterKit | ### [](https://tiptap.dev/docs/guides/migrate-from-ckeditor4#extension-configuration) Extension configuration import { Editor } from '@tiptap/core' import StarterKit from '@tiptap/starter-kit' import Image from '@tiptap/extension-image' import Table from '@tiptap/extension-table' import TableRow from '@tiptap/extension-table-row' import TableHeader from '@tiptap/extension-table-header' import TableCell from '@tiptap/extension-table-cell' import TextAlign from '@tiptap/extension-text-align' import Underline from '@tiptap/extension-underline' const editor = new Editor({ extensions: [\ StarterKit,\ Underline,\ Image.configure({\ inline: true,\ allowBase64: true,\ }),\ Table.configure({\ resizable: true,\ }),\ TableRow,\ TableHeader,\ TableCell,\ TextAlign.configure({\ types: ['heading', 'paragraph'],\ }),\ ], }) ### [](https://tiptap.dev/docs/guides/migrate-from-ckeditor4#custom-extensions) Custom extensions For CKEditor 4 custom plugins, create custom Tiptap extensions. See our [custom extensions guide](https://tiptap.dev/docs/editor/extensions/custom-extensions) for detailed instructions. [](https://tiptap.dev/docs/guides/migrate-from-ckeditor4#ui-implementation) UI implementation --------------------------------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/migrate-from-ckeditor4#toolbar-implementation) Toolbar implementation CKEditor 4's toolbar configuration translates to custom UI components in Tiptap: // CKEditor 4 toolbar config toolbar: [\ { name: 'basicstyles', items: ['Bold', 'Italic', 'Underline'] },\ { name: 'paragraph', items: ['NumberedList', 'BulletedList'] },\ { name: 'links', items: ['Link', 'Unlink'] },\ ] // Tiptap equivalent (React example) function Toolbar({ editor }) { if (!editor) return null return (Hello world!
' // Use directly in Tiptap const editor = new Editor({ content: existingContent, extensions: [StarterKit], }) While HTML works perfectly, we recommend converting it to Tiptap's JSON format for better performance and readability. For batch conversion of existing content, use the [HTML utility](https://tiptap.dev/docs/editor/api/utilities/html) to convert HTML to JSON programmatically. [](https://tiptap.dev/docs/guides/migrate-from-draftjs#editor-setup) Editor setup --------------------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/migrate-from-draftjs#installation) Installation First, install Tiptap and its dependencies: npm install @tiptap/core @tiptap/starter-kit Tiptap supports all modern frontend UI frameworks like React and Vue. Follow the framework-specific installation instructions in our [installation guides](https://tiptap.dev/docs/editor/getting-started/install) . ### [](https://tiptap.dev/docs/guides/migrate-from-draftjs#basic-editor-setup) Basic editor setup Replace your Draft.js editor with Tiptap: // Draft.js (before) import React, { useState } from 'react' import { Editor, EditorState, RichUtils } from 'draft-js' function MyDraftEditor() { const [editorState, setEditorState] = useState(EditorState.createEmpty()) const handleKeyCommand = (command) => { const newState = RichUtils.handleKeyCommand(editorState, command) if (newState) { setEditorState(newState) return 'handled' } return 'not-handled' } return (Hello World!
', }) returnHello world!
' // Use directly in Tiptap const editor = new Editor({ content: existingContent, extensions: [StarterKit], }) While HTML works perfectly, we recommend converting it to Tiptap's JSON format for better performance and readability. For batch conversion of existing content, use the [HTML utility](https://tiptap.dev/docs/editor/api/utilities/html) to convert HTML to JSON programmatically. [](https://tiptap.dev/docs/guides/migrate-from-lexical#editor-setup) Editor setup --------------------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/migrate-from-lexical#installation) Installation First, install Tiptap and its dependencies: npm install @tiptap/core @tiptap/starter-kit Tiptap supports all modern frontend UI frameworks like React and Vue. Follow the framework-specific installation instructions in our [installation guides](https://tiptap.dev/docs/editor/getting-started/install) . ### [](https://tiptap.dev/docs/guides/migrate-from-lexical#basic-editor-setup) Basic editor setup Replace your Lexical editor with Tiptap: // Lexical (before) import { createEditor } from 'lexical' import { LexicalComposer } from '@lexical/react/LexicalComposer' import { RichTextPlugin } from '@lexical/react/LexicalRichTextPlugin' import { ContentEditable } from '@lexical/react/LexicalContentEditable' const initialConfig = { namespace: 'MyEditor', theme: {}, onError: console.error, } function MyLexicalEditor() { return (Enter some text...
}
/>
Hello World!
', }) [](https://tiptap.dev/docs/guides/migrate-from-lexical#extensions) Extensions ----------------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/migrate-from-lexical#understanding-tiptaps-extension-system) Understanding Tiptap's extension system Tiptap uses a modular extension system that resembles Lexical's node and plugin architecture. Each feature is an independent extension with clear APIs. The [StarterKit](https://tiptap.dev/docs/editor/extensions/functionality/starterkit) is a bundle of all the basic extensions, and you can add or remove other extensions as needed. Explore all available extensions in our [extensions guide](https://tiptap.dev/docs/editor/extensions/overview) , or [create your own](https://tiptap.dev/docs/editor/extensions/custom-extensions) to support custom functionality and HTML elements. ### [](https://tiptap.dev/docs/guides/migrate-from-lexical#common-lexical-plugin-equivalents) Common Lexical plugin equivalents | Lexical Plugin/Node | Tiptap Extension | Notes | | --- | --- | --- | | `@lexical/rich-text` | `Bold`, `Italic` | Included in StarterKit | | `@lexical/link` | `Link` | Included in StarterKit | | `@lexical/list` | `BulletList`, `OrderedList`, `ListItem` | Included in StarterKit | | `@lexical/code` | `Code`, `CodeBlock` | Included in StarterKit | | `@lexical/table` | `Table` | Available separately | | `HeadingNode` | `Heading` | Included in StarterKit | | `QuoteNode` | `Blockquote` | Included in StarterKit | | `ImageNode` | `Image` | Available separately | | `@lexical/history` | `History` | Included in StarterKit | | `@lexical/text` | `TextStyle`, `Color` | Available separately | ### [](https://tiptap.dev/docs/guides/migrate-from-lexical#extension-configuration) Extension configuration import { Editor } from '@tiptap/core' import StarterKit from '@tiptap/starter-kit' import Image from '@tiptap/extension-image' import Table from '@tiptap/extension-table' import TableRow from '@tiptap/extension-table-row' import TableHeader from '@tiptap/extension-table-header' import TableCell from '@tiptap/extension-table-cell' import { Color } from '@tiptap/extension-color' import TextStyle from '@tiptap/extension-text-style' const editor = new Editor({ extensions: [\ StarterKit,\ Image.configure({\ inline: true,\ allowBase64: true,\ }),\ Table.configure({\ resizable: true,\ }),\ TableRow,\ TableHeader,\ TableCell,\ TextStyle,\ Color.configure({\ types: [TextStyle.name],\ }),\ ], }) ### [](https://tiptap.dev/docs/guides/migrate-from-lexical#custom-extensions) Custom extensions For Lexical custom nodes or plugins, create custom Tiptap extensions. See our [custom extensions guide](https://tiptap.dev/docs/editor/extensions/custom-extensions) for detailed instructions. [](https://tiptap.dev/docs/guides/migrate-from-lexical#ui-implementation) UI implementation ------------------------------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/migrate-from-lexical#toolbar-implementation) Toolbar implementation Lexical's toolbar plugins translate to custom UI components in Tiptap: // Lexical toolbar (before) import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext' import { FORMAT_TEXT_COMMAND } from 'lexical' function ToolbarPlugin() { const [editor] = useLexicalComposerContext() return (Hello world!
- Item 1
- Item 2
Hello World!
', }) [](https://tiptap.dev/docs/guides/migrate-from-ckeditor5#extensions) Extensions ------------------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/migrate-from-ckeditor5#understanding-tiptaps-extension-system) Understanding Tiptap's extension system Tiptap uses a modular extension system that resembles CKEditor 5's plugin architecture. Each feature is an independent extension that can be configured and customized. The [StarterKit](https://tiptap.dev/docs/editor/extensions/functionality/starterkit) is a bundle of all the basic extensions, and you can add or remove other extensions as needed. Explore all available extensions in our [extensions guide](https://tiptap.dev/docs/editor/extensions/overview) , or [create your own](https://tiptap.dev/docs/editor/extensions/custom-extensions) to support custom functionality and HTML elements. ### [](https://tiptap.dev/docs/guides/migrate-from-ckeditor5#common-ckeditor-5-plugin-equivalents) Common CKEditor 5 plugin equivalents | CKEditor 5 Plugin | Tiptap Extension | Notes | | --- | --- | --- | | `Bold` | `Bold` | Included in StarterKit | | `Italic` | `Italic` | Included in StarterKit | | `List` | `BulletList`, `OrderedList`, `ListItem` | Included in StarterKit | | `Link` | `Link` | Included in StarterKit | | `Image` | `Image` | Available separately | | `Table` | `Table` | Available separately | | `CodeBlock` | `CodeBlock` | Included in StarterKit | | `Heading` | `Heading` | Included in StarterKit | | `Blockquote` | `Blockquote` | Included in StarterKit | | `Alignment` | `TextAlign` | Available separately | | `FontColor` | `TextStyle`, `Color` | Available separately | | `FontSize` | `TextStyle`, `FontSize` | Available separately | ### [](https://tiptap.dev/docs/guides/migrate-from-ckeditor5#extension-configuration) Extension configuration import { Editor } from '@tiptap/core' import StarterKit from '@tiptap/starter-kit' import Image from '@tiptap/extension-image' import Table from '@tiptap/extension-table' import TableRow from '@tiptap/extension-table-row' import TableHeader from '@tiptap/extension-table-header' import TableCell from '@tiptap/extension-table-cell' import TextAlign from '@tiptap/extension-text-align' const editor = new Editor({ extensions: [\ StarterKit,\ Image.configure({\ inline: true,\ allowBase64: true,\ }),\ Table.configure({\ resizable: true,\ }),\ TableRow,\ TableHeader,\ TableCell,\ TextAlign.configure({\ types: ['heading', 'paragraph'],\ }),\ ], }) ### [](https://tiptap.dev/docs/guides/migrate-from-ckeditor5#custom-extensions) Custom extensions For CKEditor 5 custom plugins, create custom Tiptap extensions. See our [custom extensions guide](https://tiptap.dev/docs/editor/extensions/custom-extensions) for detailed instructions. [](https://tiptap.dev/docs/guides/migrate-from-ckeditor5#ui-implementation) UI implementation --------------------------------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/migrate-from-ckeditor5#toolbar-implementation) Toolbar implementation CKEditor 5's toolbar configuration translates to custom UI components in Tiptap: // CKEditor 5 toolbar config toolbar: ['heading', 'bold', 'italic', 'link', 'bulletedList', 'numberedList'] // Tiptap equivalent (React example) function Toolbar({ editor }) { if (!editor) return null return (${block.data.text}
` break case 'header': html += `` break case 'code': html += `${block.data.text}
${block.data.code}Hello world!
' // Use directly in Tiptap const editor = new Editor({ content: existingContent, extensions: [StarterKit], }) While HTML works perfectly, we recommend converting it to Tiptap's JSON format for better performance and readability. For batch conversion of existing content, use the [HTML utility](https://tiptap.dev/docs/editor/api/utilities/html) to convert HTML to JSON programmatically. [](https://tiptap.dev/docs/guides/migrate-from-editorjs#editor-setup) Editor setup ---------------------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/migrate-from-editorjs#installation) Installation First, install Tiptap and its dependencies: npm install @tiptap/core @tiptap/starter-kit Tiptap supports all modern frontend UI frameworks like React and Vue. Follow the framework-specific installation instructions in our [installation guides](https://tiptap.dev/docs/editor/getting-started/install) . ### [](https://tiptap.dev/docs/guides/migrate-from-editorjs#basic-editor-setup) Basic editor setup Replace your Editor.js initialization with Tiptap: // Editor.js (before) import EditorJS from '@editorjs/editorjs' import Header from '@editorjs/header' import List from '@editorjs/list' import Quote from '@editorjs/quote' import Code from '@editorjs/code' import Image from '@editorjs/image' const editor = new EditorJS({ holder: 'editorjs', tools: { header: Header, list: List, quote: Quote, code: Code, image: Image, }, }) // Tiptap (after) import { Editor } from '@tiptap/core' import StarterKit from '@tiptap/starter-kit' const editor = new Editor({ element: document.querySelector('#editor'), extensions: [StarterKit], content: 'Hello World!
', }) [](https://tiptap.dev/docs/guides/migrate-from-editorjs#extensions) Extensions ------------------------------------------------------------------------------ ### [](https://tiptap.dev/docs/guides/migrate-from-editorjs#understanding-tiptaps-extension-system) Understanding Tiptap's extension system Tiptap uses a modular extension system that differs from Editor.js's tool-based approach. Instead of discrete blocks, Tiptap uses a continuous document model with extensions providing formatting and functionality. The [StarterKit](https://tiptap.dev/docs/editor/extensions/functionality/starterkit) is a bundle of all the basic extensions, and you can add or remove other extensions as needed. Explore all available extensions in our [extensions guide](https://tiptap.dev/docs/editor/extensions/overview) , or [create your own](https://tiptap.dev/docs/editor/extensions/custom-extensions) to support custom functionality and HTML elements. ### [](https://tiptap.dev/docs/guides/migrate-from-editorjs#common-editorjs-tool-equivalents) Common Editor.js tool equivalents | Editor.js Tool | Tiptap Extension | Notes | | --- | --- | --- | | `@editorjs/paragraph` | `Paragraph` | Included in StarterKit | | `@editorjs/header` | `Heading` | Included in StarterKit | | `@editorjs/list` | `BulletList`, `OrderedList`, `ListItem` | Included in StarterKit | | `@editorjs/quote` | `Blockquote` | Included in StarterKit | | `@editorjs/code` | `CodeBlock` | Included in StarterKit | | `@editorjs/image` | `Image` | Available separately | | `@editorjs/table` | `Table` | Available separately | | `@editorjs/link` | `Link` | Included in StarterKit | | `@editorjs/marker` | `Highlight` | Available separately | | `@editorjs/delimiter` | `HorizontalRule` | Included in StarterKit | ### [](https://tiptap.dev/docs/guides/migrate-from-editorjs#extension-configuration) Extension configuration import { Editor } from '@tiptap/core' import StarterKit from '@tiptap/starter-kit' import Image from '@tiptap/extension-image' import Table from '@tiptap/extension-table' import TableRow from '@tiptap/extension-table-row' import TableHeader from '@tiptap/extension-table-header' import TableCell from '@tiptap/extension-table-cell' import Highlight from '@tiptap/extension-highlight' const editor = new Editor({ extensions: [\ StarterKit,\ Image.configure({\ inline: true,\ allowBase64: true,\ }),\ Table.configure({\ resizable: true,\ }),\ TableRow,\ TableHeader,\ TableCell,\ Highlight.configure({\ multicolor: true,\ }),\ ], }) ### [](https://tiptap.dev/docs/guides/migrate-from-editorjs#custom-extensions) Custom extensions For Editor.js custom tools, create custom Tiptap extensions. See our [custom extensions guide](https://tiptap.dev/docs/editor/extensions/custom-extensions) for detailed instructions. [](https://tiptap.dev/docs/guides/migrate-from-editorjs#ui-implementation) UI implementation -------------------------------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/migrate-from-editorjs#toolbar-implementation) Toolbar implementation Editor.js's inline toolbar can be replicated with Tiptap's toolbar components: // Tiptap toolbar (React example) function Toolbar({ editor }) { if (!editor) return null return (Example Text
`, }) Or if you want to restore the content later (e. g. after an API call has finished), you can do that too: editor.commands.setContent(`Example Text
`) Use this interactive example to fiddle around: ### [](https://tiptap.dev/docs/guides/output-json-html#option-3-yjs) Option 3: Y.js Our editor has top notch support for Y.js, which is amazing to add features like [realtime collaboration, offline editing, or syncing between devices](https://tiptap.dev/docs/collaboration/getting-started/overview) . Internally, Y.js stores a history of all changes. That can be in the browser, on a server, synced with other connected clients, or on a USB stick. But, it’s important to know that Y.js needs those stored changes. A simple JSON document is not enough to merge changes. Sure, you can import existing JSON documents to get started and get a JSON out of Y.js, but that’s more like an import/export format. It won’t be your single source. That’s important to consider when adding Y.js for one of the mentioned use cases. That said, it’s amazing and we’re about to provide an amazing backend, that makes all that a breeze. ### [](https://tiptap.dev/docs/guides/output-json-html#markdown) Markdown Tiptap already provides import, export, and REST API conversions for Markdown (including GitHub Flavored Markdown). This lets you: * **Import `.md` or GFM** files into a Tiptap editor, converting them to Tiptap JSON * **Export** Tiptap JSON to standard Markdown or GFM, letting you save or share your editor content as a `.md` file. * **Integrate server-side** (no editor required) by sending or retrieving `.md` content via our Conversion REST API. See [Markdown Conversion](https://tiptap.dev/docs/conversion/import/markdown/rest-api) for details on how to handle other Markdown features, plus examples for both in-editor workflows and server-side usage. **Tiptap v3 will deepen Markdown support.** We’re committed to making Markdown more robust and easier to integrate for advanced (AI) use cases. If you are looking to convert ProseMirror JSON to Markdown, you can use the `@tiptap/static-renderer` package, which can convert ProseMirror JSON to Markdown. See more info and examples in it's [documentation](https://tiptap.dev/docs/editor/api/utilities/static-renderer) . [](https://tiptap.dev/docs/guides/output-json-html#listen-for-changes) Listen for changes ----------------------------------------------------------------------------------------- If you want to continuously store the updated content while people write, you can [hook into events](https://tiptap.dev/docs/editor/api/events) . Here is an example how that could look like: const editor = new Editor({ // intial content content: `Example Content
`, // triggered on every change onUpdate: ({ editor }) => { const json = editor.getJSON() // send the content to an API here }, }) [](https://tiptap.dev/docs/guides/output-json-html#render) Render ----------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/output-json-html#option-1-read-only-instance-of-tiptap) Option 1: Read-only instance of Tiptap To render the saved content, set the editor to read-only. That’s how you can achieve the exact same rendering as it’s in the editor, without duplicating your CSS and other code. ### [](https://tiptap.dev/docs/guides/output-json-html#option-2-generate-html-from-prosemirror-json) Option 2: Generate HTML from ProseMirror JSON If you need to render the content on the server side, for example to generate the HTML for a blog post, which has been written in Tiptap, you’ll probably want to do just that without an actual editor instance. That’s what the `generateHTML()` is for. It’s a helper function which renders HTML without an actual editor instance. By the way, the other way is possible, too. The below examples shows how to generate JSON from HTML. ### [](https://tiptap.dev/docs/guides/output-json-html#option-3-static-renderer) Option 3: Static Renderer Generate HTML, React Elements or Markdown from ProseMirror JSON If you want to render the content in a static way, for example in a blog post, you can use the `@tiptap/static-renderer` package. It can convert ProseMirror JSON to HTML, React Elements or Markdown. npm install @tiptap/static-renderer To learn more about the static renderer, check out the [static renderer documentation](https://tiptap.dev/docs/editor/api/utilities/static-renderer) . [](https://tiptap.dev/docs/guides/output-json-html#migrate) Migrate ------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/output-json-html#from-draftjs) From Draft.js If you’re migrating from Draft.js to Tiptap, you probably have your content stored as JSON. That’s great, because Tiptap can handle that with the [draft-js-to-tiptap package](https://github.com/ueberdosis/draft-js-to-tiptap) . See more info and examples in it's [documentation](https://github.com/ueberdosis/draft-js-to-tiptap/blob/main/README.md) . ### [](https://tiptap.dev/docs/guides/output-json-html#others) Others If you’re migrating existing content to Tiptap we would recommend to get your existing output to HTML. That’s probably the best format to get your initial content into Tiptap, because ProseMirror ensures there is nothing wrong with it. Even if there are some tags or attributes that aren’t allowed (based on your configuration), Tiptap just throws them away quietly. We’re about to go through a few cases to help with that, for example we provide a PHP package to convert HTML to a compatible JSON structure: [ueberdosis/prosemirror-to-html](https://github.com/ueberdosis/html-to-prosemirror) . [Share your experiences with us!](mailto:humans@tiptap.dev) We’d like to add more information here. [](https://tiptap.dev/docs/guides/output-json-html#security) Security --------------------------------------------------------------------- There is no reason to use one or the other because of security concerns. If someone wants to send malicious content to your server, it doesn’t matter if it’s JSON or HTML. It doesn’t even matter if you’re using Tiptap or not. You should always validate user input. [PreviouslyInvalid schema handling](https://tiptap.dev/docs/guides/invalid-schema) [Next upCollaboration Auth](https://tiptap.dev/docs/guides/authentication) --- # Pro Extensions | Tiptap Editor Docs Tiptap Pro extensions add advanced capabilities to the Tiptap Editor such as versioning and AI-assisted content generation. A Tiptap account is required to access Pro extensions. Select extensions such as Snapshots, Comments, and the Content AI extension also require an active subscription. Tiptap Pro and Cloud Extensions unlock features like collaboration, version history, comments, AI-assisted editing and more. You install them from Tiptap's private NPM registry with your personal access token. ### Security warning Treat your authentication tokens like passwords to prevent unauthorized use. Each Tiptap user has a unique authentication token that does not expire. We recommend creating a dedicated user for CI/CD applications. [](https://tiptap.dev/docs/guides/pro-extensions#get-your-access-token) Get your access token --------------------------------------------------------------------------------------------- 1. Sign in to your Tiptap account (or [sign up](https://cloud.tiptap.dev/register) ). 2. Start your [trial or subscribe](https://cloud.tiptap.dev/v2/billing) to a Tiptap plan. 3. Copy your personal NPM token from [My features → Pro Extensions](https://cloud.tiptap.dev/v2/features/pro-extensions) . [](https://tiptap.dev/docs/guides/pro-extensions#configure-authentication-per-project) Configure authentication per project --------------------------------------------------------------------------------------------------------------------------- Add the registry and token to the package-manager config in your project root. ### Tip Reference `TIPTAP_PRO_TOKEN` as an environment variable to avoid committing credentials. ### [](https://tiptap.dev/docs/guides/pro-extensions#npm-pnpm-or-yarn-classic) npm, pnpm, or Yarn Classic Create or update .npmrc: @tiptap-pro:registry=https://registry.tiptap.dev/ //registry.tiptap.dev/:_authToken=${TIPTAP_PRO_TOKEN} ### [](https://tiptap.dev/docs/guides/pro-extensions#yarn-modern-yarn-2) Yarn Modern (Yarn 2+) Create or update .yarnrc.yml: npmScopes: tiptap-pro: npmAlwaysAuth: true npmRegistryServer: "https://registry.tiptap.dev/" npmAuthToken: ${TIPTAP_PRO_TOKEN} Add `.npmrc` or `.yarnrc.yml` to `.gitignore`. ### Warning This is essential to avoid leaking your credentials if you specify the authentication token directly in the configuration file. Once you've configured authentication for a project, you can install Pro Extensions like any other Editor extension. If you use environment variables, pass the authentication token during installation: TIPTAP_PRO_TOKEN=actual-auth-token npm install --save @tiptap-pro/extension-comments [](https://tiptap.dev/docs/guides/pro-extensions#configure-global-authentication) Configure global authentication ----------------------------------------------------------------------------------------------------------------- You can set up authentication once for **all** of your projects by updating the package manager configuration file at the user level. This is useful for CI/CD environments. 1. Sign in to your Tiptap account (or create a free one). 2. Start your [trial or subscribe](https://cloud.tiptap.dev/v2/billing) to a Tiptap plan. 3. (Optional) [Invite a team member](https://cloud.tiptap.dev/v2/team/members) for your CI/CD pipeline. 4. Copy your personal NPM token from [My features → Pro Extensions](https://cloud.tiptap.dev/v2/features/pro-extensions) . ### [](https://tiptap.dev/docs/guides/pro-extensions#npm-or-yarn-classic) npm or Yarn Classic npm config set "@tiptap-pro:registry" https://registry.tiptap.dev/ npm config set "//registry.tiptap.dev/:_authToken" actual-auth-token ### [](https://tiptap.dev/docs/guides/pro-extensions#yarn-modern) Yarn Modern yarn config set --home npmScopes.@tiptap-pro.npmRegistryServer "https://registry.tiptap.dev/" yarn config set --home npmScopes.@tiptap-pro.npmAlwaysAuth "true" yarn config set --home npmScopes.@tiptap-pro.npmAuthToken "actual-auth-token" ### [](https://tiptap.dev/docs/guides/pro-extensions#pnpm) pnpm pnpm config set --global "@tiptap-pro:registry" https://registry.tiptap.dev/ pnpm config set "//registry.tiptap.dev/:_authToken" actual-auth-token You can now install any Tiptap Pro extension in any repository: npm install --save @tiptap-pro/extension-comments [Next upFAQ](https://tiptap.dev/docs/guides/faq) --- # TypeScript | Tiptap Editor Docs The whole Tiptap codebase is written in TypeScript. If you haven’t heard of it or never used it, no worries. You don’t have to. TypeScript extends JavaScript by adding types (hence the name). It adds new syntax, which doesn’t exist in Vanilla JavaScript. It’s actually removed before running in the browser, but this step – the compilation – is important to find bugs early. It checks if you pass the right types of data to functions. For a big and complex project, that’s very valuable. It means we’ll get notified of lots of bugs, before shipping code to you. **Anyway, if you don’t use TypeScript in your project, that’s fine.** You will still be able to use Tiptap and nevertheless get a nice autocomplete for the Tiptap API (if your editor supports it, but most do). If you are using TypeScript in your project and want to extend Tiptap, there are two types that are good to know about. [](https://tiptap.dev/docs/guides/typescript#types) Types --------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/typescript#options-types) Options types To extend or create default options for an extension, you’ll need to define a custom type, here is an example: import { Extension } from '@tiptap/core' export interface CustomExtensionOptions { awesomeness: number } const CustomExtension = Extension.createHello world!
' // Use directly in Tiptap const editor = new Editor({ content: existingContent, extensions: [StarterKit], }) While HTML works perfectly, we recommend converting it to Tiptap's JSON format for better performance and readability. For batch conversion of existing content, use the [HTML utility](https://tiptap.dev/docs/editor/api/utilities/html) to convert HTML to JSON programmatically. [](https://tiptap.dev/docs/guides/migrate-from-quill#editor-setup) Editor setup ------------------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/migrate-from-quill#installation) Installation First, install Tiptap and its dependencies: npm install @tiptap/core @tiptap/starter-kit Tiptap supports all modern frontend UI frameworks like React and Vue. Follow the framework-specific installation instructions in our [installation guides](https://tiptap.dev/docs/editor/getting-started/install) . ### [](https://tiptap.dev/docs/guides/migrate-from-quill#basic-editor-setup) Basic editor setup Replace your Quill initialization with Tiptap: // Quill (before) const quill = new Quill('#editor', { theme: 'snow', modules: { toolbar: [\ ['bold', 'italic', 'underline'],\ ['link', 'image'],\ [{ list: 'ordered' }, { list: 'bullet' }],\ [{ header: [1, 2, 3, false] }],\ ], }, }) // Tiptap (after) import { Editor } from '@tiptap/core' import StarterKit from '@tiptap/starter-kit' const editor = new Editor({ element: document.querySelector('#editor'), extensions: [StarterKit], content: 'Hello World!
', }) [](https://tiptap.dev/docs/guides/migrate-from-quill#extensions) Extensions --------------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/migrate-from-quill#understanding-tiptaps-extension-system) Understanding Tiptap's extension system Tiptap uses a modular extension system that resembles Quill's module system. Each feature is an independent extension that can be configured and customized. The [StarterKit](https://tiptap.dev/docs/editor/extensions/functionality/starterkit) is a bundle of all the basic extensions, and you can add or remove other extensions as needed. Explore all available extensions in our [extensions guide](https://tiptap.dev/docs/editor/extensions/overview) , or [create your own](https://tiptap.dev/docs/editor/extensions/custom-extensions) to support custom functionality and HTML elements. ### [](https://tiptap.dev/docs/guides/migrate-from-quill#common-quill-module-equivalents) Common Quill module equivalents | Quill Feature | Tiptap Extension | Notes | | --- | --- | --- | | Bold | `Bold` | Included in StarterKit | | Italic | `Italic` | Included in StarterKit | | Underline | `Underline` | Included in StarterKit | | Link | `Link` | Included in StarterKit | | Image | `Image` | Available separately | | List (bullet/ordered) | `BulletList`, `OrderedList`, `ListItem` | Included in StarterKit | | Header | `Heading` | Included in StarterKit | | Blockquote | `Blockquote` | Included in StarterKit | | Code Block | `CodeBlock` | Included in StarterKit | | Strike | `Strike` | Included in StarterKit | | Color | `TextStyle`, `Color` | Available separately | | Background | `TextStyle`, `Highlight` | Available separately | | Align | `TextAlign` | Available separately | ### [](https://tiptap.dev/docs/guides/migrate-from-quill#extension-configuration) Extension configuration import { Editor } from '@tiptap/core' import StarterKit from '@tiptap/starter-kit' import Image from '@tiptap/extension-image' import TextAlign from '@tiptap/extension-text-align' import { Color } from '@tiptap/extension-color' import TextStyle from '@tiptap/extension-text-style' const editor = new Editor({ extensions: [\ StarterKit,\ Image.configure({\ inline: true,\ allowBase64: true,\ }),\ TextAlign.configure({\ types: ['heading', 'paragraph'],\ }),\ TextStyle,\ Color.configure({\ types: [TextStyle.name, ListItem.name],\ }),\ ], }) ### [](https://tiptap.dev/docs/guides/migrate-from-quill#custom-extensions) Custom extensions For Quill custom modules or blots, create custom Tiptap extensions. See our [custom extensions guide](https://tiptap.dev/docs/editor/extensions/custom-extensions) for detailed instructions. [](https://tiptap.dev/docs/guides/migrate-from-quill#ui-implementation) UI implementation ----------------------------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/migrate-from-quill#toolbar-implementation) Toolbar implementation Quill's toolbar configuration translates to custom UI components in Tiptap: // Quill toolbar config toolbar: [\ ['bold', 'italic', 'underline'],\ ['link', 'image'],\ [{ list: 'ordered' }, { list: 'bullet' }],\ [{ header: [1, 2, 3, false] }],\ ] // Tiptap equivalent (React example) function Toolbar({ editor }) { if (!editor) return null return (Hello world!
' // Use directly in Tiptap const editor = new Editor({ content: existingContent, extensions: [StarterKit], }) While HTML works perfectly, we recommend converting it to Tiptap's JSON format for better performance and readability. For batch conversion of existing content, use the [HTML utility](https://tiptap.dev/docs/editor/api/utilities/html) to convert HTML to JSON programmatically. [](https://tiptap.dev/docs/guides/migrate-from-tinymce#editor-setup) Editor setup --------------------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/migrate-from-tinymce#installation) Installation First, install Tiptap and its dependencies: npm install @tiptap/core @tiptap/starter-kit Tiptap supports all modern frontend UI frameworks like React and Vue. Follow the framework-specific installation instructions in our [installation guides](https://tiptap.dev/docs/editor/getting-started/install) . ### [](https://tiptap.dev/docs/guides/migrate-from-tinymce#basic-editor-setup) Basic editor setup Replace your TinyMCE initialization with Tiptap: // TinyMCE (before) tinymce.init({ selector: '#editor', plugins: 'lists link image table code', toolbar: 'undo redo | bold italic | bullist numlist | link image', }) // Tiptap (after) import { Editor } from '@tiptap/core' import StarterKit from '@tiptap/starter-kit' const editor = new Editor({ element: document.querySelector('#editor'), extensions: [StarterKit], content: 'Hello World!
', }) [](https://tiptap.dev/docs/guides/migrate-from-tinymce#extensions) Extensions ----------------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/migrate-from-tinymce#understanding-tiptaps-extension-system) Understanding Tiptap's extension system Tiptap uses a modular extension system that resembles TinyMCE's plugin architecture. Each feature is an extension that can be configured independently. The [StarterKit](https://tiptap.dev/docs/editor/extensions/functionality/starterkit) is a bundle of all the basic extensions, and you can add or remove other extensions as needed. Explore all available extensions in our [extensions guide](https://tiptap.dev/docs/editor/extensions/overview) , or [create your own](https://tiptap.dev/docs/editor/extensions/custom-extensions) to support custom functionality and HTML elements. ### [](https://tiptap.dev/docs/guides/migrate-from-tinymce#common-tinymce-plugin-equivalents) Common TinyMCE plugin equivalents | TinyMCE Plugin | Tiptap Extension | Notes | | --- | --- | --- | | `lists` | `BulletList`, `OrderedList`, `ListItem` | Included in StarterKit | | `link` | `Link` | Included in StarterKit | | `image` | `Image` | Available separately | | `table` | `Table` | Available separately | | `code` | `Code`, `CodeBlock` | Included in StarterKit | | `textcolor` | `TextStyle`, `Color` | Available separately | | `fontsize` | `TextStyle`, `FontSize` | Available separately | | `align` | `TextAlign` | Available separately | ### [](https://tiptap.dev/docs/guides/migrate-from-tinymce#extension-configuration) Extension configuration import { Editor } from '@tiptap/core' import StarterKit from '@tiptap/starter-kit' import Image from '@tiptap/extension-image' import Table from '@tiptap/extension-table' import TableRow from '@tiptap/extension-table-row' import TableHeader from '@tiptap/extension-table-header' import TableCell from '@tiptap/extension-table-cell' const editor = new Editor({ extensions: [\ StarterKit,\ // Add and configure extensions\ Image.configure({\ inline: true,\ allowBase64: true,\ }),\ Table.configure({\ resizable: true,\ }),\ TableRow,\ TableHeader,\ TableCell,\ ], }) ### [](https://tiptap.dev/docs/guides/migrate-from-tinymce#custom-extensions) Custom extensions For TinyMCE custom plugins, you can create custom Tiptap extensions. See our [custom extensions guide](https://tiptap.dev/docs/editor/extensions/custom-extensions) for detailed instructions. [](https://tiptap.dev/docs/guides/migrate-from-tinymce#ui-implementation) UI implementation ------------------------------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/migrate-from-tinymce#toolbar-implementation) Toolbar implementation TinyMCE's toolbar configuration translates to custom UI components in Tiptap: // TinyMCE toolbar config toolbar: 'undo redo | bold italic | bullist numlist' // Tiptap equivalent (React example) function Toolbar({ editor }) { if (!editor) return null return ({children}
\ case 'heading-one':\ return{children}
\ case 'heading-two':\ return{children}
\ // Add more block types as needed\ }\ }\ if (obj.object === 'mark') {\ switch (obj.type) {\ case 'bold':\ return {children}\ case 'italic':\ return {children}\ // Add more mark types as needed\ }\ }\ },\ },\ ] const htmlContent = serialize(slateValue, { rules }) // Use HTML content in Tiptap const editor = new Editor({ content: htmlContent, extensions: [StarterKit], }) For simpler Slate structures, you might be able to map directly to Tiptap's JSON format: // Example Slate to Tiptap JSON conversion function slateToTiptap(slateNodes) { return { type: 'doc', content: slateNodes.map((node) => { if (node.type === 'paragraph') { return { type: 'paragraph', content: node.children.map((child) => ({ type: 'text', text: child.text, marks: child.bold ? [{ type: 'bold' }] : [], })), } } // Add more node type mappings }), } } const tiptapContent = slateToTiptap(slateValue.document.nodes) const editor = new Editor({ content: tiptapContent, extensions: [StarterKit], }) While HTML works perfectly, we recommend converting it to Tiptap's JSON format for better performance and readability. For batch conversion of existing content, use the [HTML utility](https://tiptap.dev/docs/editor/api/utilities/html) to convert HTML to JSON programmatically. [](https://tiptap.dev/docs/guides/migrate-from-slate#editor-setup) Editor setup ------------------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/migrate-from-slate#installation) Installation First, install Tiptap and its dependencies: npm install @tiptap/core @tiptap/starter-kit Tiptap supports all modern frontend UI frameworks like React and Vue. Follow the framework-specific installation instructions in our [installation guides](https://tiptap.dev/docs/editor/getting-started/install) . ### [](https://tiptap.dev/docs/guides/migrate-from-slate#basic-editor-setup) Basic editor setup Replace your Slate editor with Tiptap: // Slate (before) import { createEditor } from 'slate' import { Slate, Editable, withReact } from 'slate-react' const [editor] = useState(() => withReact(createEditor())) const [value, setValue] = useState(initialValue) return (Hello World!
', }) [](https://tiptap.dev/docs/guides/migrate-from-slate#extensions) Extensions --------------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/migrate-from-slate#understanding-tiptaps-extension-system) Understanding Tiptap's extension system Tiptap uses a modular extension system that resembles Slate's plugin system. Each feature is an independent extension with clear APIs and configuration options. The [StarterKit](https://tiptap.dev/docs/editor/extensions/functionality/starterkit) is a bundle of all the basic extensions, and you can add or remove other extensions as needed. Explore all available extensions in our [extensions guide](https://tiptap.dev/docs/editor/extensions/overview) , or [create your own](https://tiptap.dev/docs/editor/extensions/custom-extensions) to support custom functionality and HTML elements. ### [](https://tiptap.dev/docs/guides/migrate-from-slate#common-slate-plugin-equivalents) Common Slate plugin equivalents | Slate Concept | Tiptap Extension | Notes | | --- | --- | --- | | Bold mark | `Bold` | Included in StarterKit | | Italic mark | `Italic` | Included in StarterKit | | Underline mark | `Underline` | Included in StarterKit | | Link mark | `Link` | Included in StarterKit | | Image block | `Image` | Available separately | | List blocks | `BulletList`, `OrderedList`, `ListItem` | Included in StarterKit | | Heading blocks | `Heading` | Included in StarterKit | | Blockquote block | `Blockquote` | Included in StarterKit | | Code block | `CodeBlock` | Included in StarterKit | | Table blocks | `Table` | Available separately | ### [](https://tiptap.dev/docs/guides/migrate-from-slate#extension-configuration) Extension configuration import { Editor } from '@tiptap/core' import StarterKit from '@tiptap/starter-kit' import Image from '@tiptap/extension-image' import Table from '@tiptap/extension-table' import TableRow from '@tiptap/extension-table-row' import TableHeader from '@tiptap/extension-table-header' import TableCell from '@tiptap/extension-table-cell' const editor = new Editor({ extensions: [\ StarterKit,\ Image.configure({\ inline: true,\ allowBase64: true,\ }),\ Table.configure({\ resizable: true,\ }),\ TableRow,\ TableHeader,\ TableCell,\ ], }) ### [](https://tiptap.dev/docs/guides/migrate-from-slate#custom-extensions) Custom extensions For Slate custom plugins, create custom Tiptap extensions. See our [custom extensions guide](https://tiptap.dev/docs/editor/extensions/custom-extensions) for detailed instructions. [](https://tiptap.dev/docs/guides/migrate-from-slate#ui-implementation) UI implementation ----------------------------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/migrate-from-slate#toolbar-implementation) Toolbar implementation Slate's custom toolbar components translate to Tiptap UI components: // Slate toolbar (before) const Toolbar = () => { const editor = useSlate() return (Hello World!
', }) return (Hello World!
', immediatelyRender: false, }) return (Loading editor...
{JSON.stringify(editor.getJSON(), null, 2)}
}
However, for new code, we recommend using `useTiptap()` which provides additional context like the `isReady` flag.
[](https://tiptap.dev/docs/guides/react-composable-api#api-reference)
API Reference
-----------------------------------------------------------------------------------
### [](https://tiptap.dev/docs/guides/react-composable-api#tiptap-component)
Tiptap component
The root provider component that makes the editor instance available via React context.
**Props:**
| Prop | Type | Description |
| --- | --- | --- |
| `instance` | `Editor \| null` | The editor instance from `useEditor()` |
| `children` | `ReactNode` | Child components |
**Example:**
. | | **Migration from `tippy.js` to `floating-ui`** | We replaced the outdated `tippy.js` library with the new `floating-ui` library. This change improves the performance and reliability of our menus and tooltips. | | **Changes to our Text Style API** | The `@tiptap/extension-text-style` package has seen API updates providing a new `TextStyleKit` extension that encapsulates all possible text styling functionalities in one extension. Default options were also updated. | | **Commands were changed** | The behavior or names of commands were changed. `clearContent` and `setContent` now emit updates correctly while `setContent` also received a change to its parameters. `insertContent` was changed to prevent unwanted text splitting. | | **NodeView `getPos` now can return `undefined`** | `nodeView.getPos()` can now return `undefined` making a check for `undefined` necessary to handle this case properly. | | **`editor.getCharacterCount()` was removed** | The `editor.getCharacterCount()` method was removed. It was marked as deprecated in the previous version and is now removed. You can use `editor.storage.characterCount.characters()` instead while using the `CharacterCount` extension. | | **`considerAnyAsEmpty` option removed from placeholder extension** | The `considerAnyAsEmpty` option was removed from the placeholder extension as it was deprecated already and wasn't respected in the previous version. | | **Stricter Typing** | 3.0.0 brings stricter typing to the editor. This change improves the overall type safety of the editor and makes it easier to work with but might require some adjustments in your code. We recommend using TypeScript to benefit from the improved type safety. | | **Moved Utility Extensions** | We moved all our utility extensions like `History`, `Placeholder`, `CharacterCount`, `DropCursor`, `GapCursor`, `TrailingNode`, `Focus`, and `Selection` to the new `@tiptap/extensions` package. | | **Renamed Collaboration Cursor** | The `CollaborationCursor` extension was renamed to `CollaborationCaret` as we felt cursors was too general and could clash with potential other cursor types in the future. | | **Renamed History Extension** | The `History` extension was renamed to `UndoRedo` to better reflect its purpose and avoid confusion with the collaborative History feature. This also includes the `history` option on the `StarterKit`. | [](https://tiptap.dev/docs/resources/whats-new#new-features) New features ------------------------------------------------------------------------- * **New `@tiptap/extensions` extension** - The new `@tiptap/extensions` package includes and combines multiple utility extensions. [Read more](https://tiptap.dev/docs/guides/upgrade-tiptap-v2#extensions-package) . * **New [MarkView](https://prosemirror.net/docs/ref/#view.MarkView) support** - MarkViews are now supported by Tiptap. This can be useful to render custom HTML for marks. [Read more](https://tiptap.dev/docs/editor/extensions/custom-extensions/mark-views) . * **Improved Server-Side Rendering** - The editor can now run on SSR environments without rendering the editor content. [Read more](https://tiptap.dev/docs/guides/upgrade-tiptap-v2#server-side-rendering) . * **Deletes can now be tracked as an event** - Editor deletions can now be tracked as an event. [Read more](https://tiptap.dev/docs/editor/api/events#list-of-available-events) . * **Nodes and marks have new attribute validation support** - Validating attributes on nodes or marks is now supported. * **StarterKit updates** - The StarterKit was made more powerful now including more extensions by default. [Read more](https://tiptap.dev/docs/guides/upgrade-tiptap-v2#starterkit-updates) . * **TableKit** - The new `TableKit` extension allows you to register all important table extensions in one package. [Read more](https://tiptap.dev/docs/editor/extensions/functionality/table-kit) . * **ListKit** - The new `ListKit` extension allows you to register all important list extensions in one package. [Read more](https://tiptap.dev/docs/editor/extensions/functionality/list-kit) . * **TextStyleKit** - The new `TextStyleKit` extension registers all important text-style extensions in one package. [Read more](https://tiptap.dev/docs/editor/extensions/functionality/text-style-kit) . * **New `rewriteUnknownContent` helper** - This helper function can be imported from the `@tiptap/core`. * **New `unmount` as an alternative to destroying the editor** - The editor instance now supports an `unmount` method which allows for mounting and unmounting the editor to the DOM. This encourages re-use of editor instances by preserving all the same options between instances. This is different from the `destroy` method, which will unmount, emit the `destroy` event, and remove all event listeners. * **New `toggleTextStyle` command for text styles** - The `toggleTextStyle` command allows you to toggle text styles on and off. This is useful for toggling text styles like bold or italic. * **Static Renderer** - The Static Renderer helps render JSON content as HTML, Markdown, or React components without an editor instance. [Read more](https://tiptap.dev/docs/editor/api/utilities/static-renderer) . * **JSX Renderer** - With 3.0.0 you will have the ability to use **framework agnostic** JSX for the `renderHTML` function of your extensions. [Read more](https://tiptap.dev/docs/editor/api/utilities/jsx) . ### [](https://tiptap.dev/docs/resources/whats-new#improvements) Improvements * **Improved transaction handling** - Transactions are now handled more efficiently and reliably. This change improves the overall performance of the editor. * **`focusEvent` plugin key is exported** - You can now import the `focusEvent` plugin key if needed from the core package. * **Improvements on mobile devices** - The 3.0.0 release brings improvements for mobile devices primarily focusing on touch events. * **Minor IME bugfixes** - The 3.0.0 release includes a few minor bugfixes for IME input handling. * **TextStyle can now consume style attributes** - The `TextStyle` extension can now consume styles from the style attribute and will skip parsing of other styles if there was an override defined in the style attribute. See [this Github Comment](https://github.com/ueberdosis/tiptap/discussions/5912#discussioncomment-11716337) . * **TableView on `Table` extension is now importable** - The `TableView` class on the `Table` extension is now importable to allow for custom table views that still are resizable. ### [](https://tiptap.dev/docs/resources/whats-new#additional-changes) Additional changes * **HTML parsing with `happy-dom-without-node`** - We now use `happy-dom-without-node` to parse HTML as a lightweight alternative to `zeed-dom`. * **Various smaller bugfixes** - The 3.0.0 release includes various smaller bugfixes and improvements to the overall performance of the editor. [](https://tiptap.dev/docs/resources/whats-new#whats-next-in-tiptap-3x) What's next in Tiptap 3.X? -------------------------------------------------------------------------------------------------- We're already exploring future features for releases beyond Tiptap 3.0. * **Content migrations**: Migrations allow you to rewrite your document JSON to align with your current schema, facilitating document updates during schema changes with fully customizable solutions tailored to your needs. * **Markdown support**: Enhance your editing capabilities by enabling the editor to both accept and output content in markdown, meeting the demands of modern applications and leveraging the strengths of LLMs in markdown generation. * **Decorations API**: The new Decorations API allows you to influence document presentation without altering its content, providing an intuitive way to add visual enhancements beyond complex ProseMirror internals. [PreviouslyOverview](https://tiptap.dev/docs) [Next upEditor](https://tiptap.dev/docs/editor/getting-started/overview) --- # Upgrade v1 to v2 | Tiptap Collaboration Docs First of all, Tiptap v1 isn’t supported anymore and won’t receive any further updates. If you’re still using Tiptap v1, you can find the documentation [here](https://v1.tiptap.dev/) , but we strongly recommend that you upgrade to version 2. Yes, it’s tedious work to upgrade your favorite text editor to a new API, but we made sure you’ve got enough reasons to upgrade to the newest version. * Autocompletion in your IDE (thanks to TypeScript) * Amazing documentation with 100+ pages and 100+ interactive examples * Active development, new features in the making, new releases every week * Tons of new extensions * Well-tested code base The new API will look pretty familiar to you, but there are a ton of changes though. To make the upgrade a little bit easier, here is everything you need to know: [](https://tiptap.dev/docs/guides/upgrade-tiptap-v1#uninstall-tiptap-v1) Uninstall Tiptap v1 -------------------------------------------------------------------------------------------- The whole package structure has changed, we even moved to another npm namespace, so you’ll need to remove the old version entirely before upgrading to Tiptap 2. Otherwise you’ll run into an exception, for example “looks like multiple versions of prosemirror-model were loaded”. npm uninstall tiptap tiptap-commands tiptap-extensions tiptap-utils [](https://tiptap.dev/docs/guides/upgrade-tiptap-v1#install-tiptap-v2) Install Tiptap v2 ---------------------------------------------------------------------------------------- Once you have uninstalled the old version of Tiptap, install the new Vue 2 package, the ProseMirror library and the starter kit: npm install @tiptap/vue-2 @tiptap/pm @tiptap/starter-kit [](https://tiptap.dev/docs/guides/upgrade-tiptap-v1#keep-tiptap-v2-up-to-date) Keep Tiptap v2 up to date -------------------------------------------------------------------------------------------------------- We are constantly releasing updates to Tiptap. Unfortunately, for npm there is no integrated tool to easily update your dependencies, but you can use the `npm-check` package: npm install -g npm-check npm-check -u [](https://tiptap.dev/docs/guides/upgrade-tiptap-v1#explicitly-register-the-document-text-and-paragraph-extensions) Explicitly register the Document, Text and Paragraph extensions ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Tiptap 1 tried to hide a few required extensions from you with the default setting `useBuiltInExtensions: true`. That setting has been removed and you’re required to import all extensions. Be sure to explicitly import at least the [`Document`](https://tiptap.dev/docs/editor/extensions/nodes/document) , [`Paragraph`](https://tiptap.dev/docs/editor/extensions/nodes/paragraph) and [`Text`](https://tiptap.dev/docs/editor/extensions/nodes/text) extensions. import Document from '@tiptap/extension-document' import Paragraph from '@tiptap/extension-paragraph' import Text from '@tiptap/extension-text' new Editor({ extensions: [\ Document,\ Paragraph,\ Text,\ // all your other extensions\ ], }) And we removed some settings: `dropCursor`, `enableDropCursor`, and `enableGapCursor`. Those are separate extensions now: [`Dropcursor`](https://tiptap.dev/docs/editor/extensions/functionality/dropcursor) and [`Gapcursor`](https://tiptap.dev/docs/editor/extensions/functionality/gapcursor) . You probably want to load them, but if you don’t, just ignore this. [](https://tiptap.dev/docs/guides/upgrade-tiptap-v1#new-names-for-most-extensions) New names for most extensions ---------------------------------------------------------------------------------------------------------------- We switched to lowerCamelCase, so there’s a lot type names that changed. If you stored your content as JSON you need to loop through it and rename them. Sorry for that one. | Old type | New type | | --- | --- | | ~`bullet_list`~ | `bulletList` | | ~`code_block`~ | `codeBlock` | | ~`hard_break`~ | `hardBreak` | | ~`horizontal_rule`~ | `horizontalRule` | | ~`list_item`~ | `listItem` | | ~`ordered_list`~ | `orderedList` | | ~`table_cell`~ | `tableCell` | | ~`table_header`~ | `tableHeader` | | ~`table_row`~ | `tableRow` | | ~`todo_list`~ | `taskList` (new name!) | | ~`todo_item`~ | `taskItem` (new name!) | [](https://tiptap.dev/docs/guides/upgrade-tiptap-v1#removed-methods) Removed methods ------------------------------------------------------------------------------------ We removed the `.state()` method. No worries though, it’s still available through `editor.state`. [](https://tiptap.dev/docs/guides/upgrade-tiptap-v1#new-extension-api) New extension API ---------------------------------------------------------------------------------------- In case you’ve built some custom extensions for your project, you’re required to rewrite them to fit the new API. No worries, you can keep a lot of your work though. The `schema`, `commands`, `keys`, `inputRules` and `pasteRules` all work like they did before. It’s just different how you register them. import { Node } from '@tiptap/core' const CustomExtension = Node.create({ name: 'custom_extension', addOptions() { … }, addAttributes() { … }, parseHTML() { … }, renderHTML({ node, HTMLAttributes }) { … }, addCommands() { … }, addKeyboardShortcuts() { … }, addInputRules() { … }, // and more … }) Read more about [all the nifty details building custom extensions](https://tiptap.dev/docs/editor/extensions/custom-extensions) in our guide. [](https://tiptap.dev/docs/guides/upgrade-tiptap-v1#renamed-settings-and-methods) Renamed settings and methods -------------------------------------------------------------------------------------------------------------- [We renamed a lot of settings and methods](https://tiptap.dev/docs/editor/api/editor) . Hopefully you can migrate to the new API with search & replace. Here is a list of what changed: | Old name | New name | | --- | --- | | ~`autoFocus`~ | `autofocus` | [](https://tiptap.dev/docs/guides/upgrade-tiptap-v1#renamed-commands) Renamed commands -------------------------------------------------------------------------------------- All new extensions come with specific commands to set, unset and toggle styles. So instead of `.bold()`, it’s now `.toggleBold()`. Also, we switched to lowerCamelCase, below are a few examples. Oh, and we renamed `todo_list`, to `taskList`, sorry for that one. | Old command | New command | | --- | --- | | `.redo()` | `.redo()` (nothing changed) | | `.undo()` | `.undo()` (nothing changed) | | ~`.todo_list()`~ | `.toggleTaskList()` (new name!) | | ~`.blockquote()`~ | `.toggleBlockquote()` | | ~`.bold()`~ | `.toggleBold()` | | ~`.bullet_list()`~ | `.toggleBulletList()` | | ~`.code()`~ | `.toggleCode()` | | ~`.code_block()`~ | `.toggleCodeBlock()` | | ~`.hard_break()`~ | `.setHardBreak()` | | ~`.heading()`~ | `.toggleHeading()` | | ~`.horizontal_rule()`~ | `.setHorizontalRule()` | | ~`.italic()`~ | `.toggleItalic()` | | ~`.link()`~ | `.toggleLink()` | | ~`.ordered_list()`~ | `.toggleOrderedList()` | | ~`.paragraph()`~ | `.setParagraph()` | | ~`.strike()`~ | `.toggleStrike()` | | ~`.underline()`~ | `.toggleUnderline()` | | … | … | [](https://tiptap.dev/docs/guides/upgrade-tiptap-v1#menubar-bubblemenu-and-floatingmenu) MenuBar, BubbleMenu and FloatingMenu ----------------------------------------------------------------------------------------------------------------------------- Read the dedicated [guide on creating menus](https://tiptap.dev/docs/editor/getting-started/style-editor/custom-menus) to migrate your menus. [](https://tiptap.dev/docs/guides/upgrade-tiptap-v1#commands-can-be-chained-now) Commands can be chained now ------------------------------------------------------------------------------------------------------------ Most commands can be combined to one call now. That’s shorter than separate function calls in most cases. Here is an example to make the selected text bold: editor.chain().focus().toggleBold().run() The `.chain()` is required to start a new chain and the `.run()` is needed to actually execute all the commands in between. Read more about [the new Tiptap commands](https://tiptap.dev/docs/editor/api/commands) in our API documentation. [](https://tiptap.dev/docs/guides/upgrade-tiptap-v1#focus-isnt-called-on-every-command-anymore) .focus() isn’t called on every command anymore ---------------------------------------------------------------------------------------------------------------------------------------------- We tried to hide the `.focus()` command from you with Tiptap 1 and executed that on every command. That led to issues in specific use cases, where you want to run a command, but don’t want to focus the editor. With Tiptap v2 you have to explicitly call the `focus()` and you probably want to do that in a lot of places. Here is an example: editor.chain().focus().toggleBold().run() [](https://tiptap.dev/docs/guides/upgrade-tiptap-v1#event-callbacks-have-fewer-parameters) Event callbacks have fewer parameters -------------------------------------------------------------------------------------------------------------------------------- The new event callbacks have fewer parameters. The same things should be available through `this.` now. [Read more about events here.](https://tiptap.dev/docs/editor/api/events) [](https://tiptap.dev/docs/guides/upgrade-tiptap-v1#collaborative-editing) Collaborative editing ------------------------------------------------------------------------------------------------ The reference implementation for collaborative editing uses Y.js now. That’s a whole different thing. You still can use the Tiptap 1 extension, but it’s up to you to adapt it to the new extension API. If you’ve done this, don’t forget to share it with us so we can link to it from here! Read more about [the new collaborative editing experience](https://tiptap.dev/docs/collaboration/getting-started/install) in our guide. [](https://tiptap.dev/docs/guides/upgrade-tiptap-v1#marks-dont-support-node-view-anymore) Marks don’t support node view anymore ------------------------------------------------------------------------------------------------------------------------------- For marks, node views are [not well supported in ProseMirror](https://discuss.prosemirror.net/t/there-is-a-bug-in-marks-nodeview/2722/2) . There is also [a related issue](https://github.com/ueberdosis/tiptap/issues/613) for Tiptap 1. That’s why we removed it in Tiptap 2. [PreviouslyOffline Collaboration](https://tiptap.dev/docs/guides/offline-support) [Next upUpgrade Tiptap V2](https://tiptap.dev/docs/guides/upgrade-tiptap-v2) --- # Upgrade v2 to v3 | Tiptap Collaboration Docs Tiptap v3 is a major update with breaking changes. This guide will help you upgrade your Tiptap v2 project to version 3. [](https://tiptap.dev/docs/guides/upgrade-tiptap-v2#breaking-changes) Breaking Changes -------------------------------------------------------------------------------------- ### [](https://tiptap.dev/docs/guides/upgrade-tiptap-v2#package-changes) Package Changes * UMD builds have been removed (now using tsup) Some packages may have been removed or renamed, so you may need to update your imports and dependencies. Here are some common changes: Table packages - import Table from '@tiptap/extension-table' - import TableRow from '@tiptap/extension-table-row' - import TableCell from '@tiptap/extension-table-cell' - import TableHeader from '@tiptap/extension-table-header' + import { Table, TableRow, TableCell, TableHeader } from '@tiptap/extension-table' List packages - import BulletList from '@tiptap/extension-bullet-list' - import OrderedList from '@tiptap/extension-ordered-list' - import ListItem from '@tiptap/extension-list-item' - import ListKeymap from '@tiptap/extension-list-keymap' - import TaskList from '@tiptap/extension-task-list' - import TaskItem from '@tiptap/extension-task-item' + import { BulletList, OrderedList, ListItem, ListKeymap, TaskList, TaskItem } from '@tiptap/extension-list' Extensions - import Focus from '@tiptap/extension-focus' - import Placeholder from '@tiptap/extension-placeholder' - import History from '@tiptap/extension-history' - import Dropcursor from '@tiptap/extension-dropcursor' - import Gapcursor from '@tiptap/extension-gapcursor' - import CharacterCount from '@tiptap/extension-character-count' + import { Focus, Placeholder, UndoRedo, Dropcursor, Gapcursor, CharacterCount } from '@tiptap/extensions' CollaborationCursor - import CollaborationCursor from '@tiptap/extension-collaboration-cursor' + import CollaborationCaret from '@tiptap/extension-collaboration-caret' Collaboration History - import CollaborationHistory from '@tiptap-pro/extension-collaboration-history' + import Snapshot from '@tiptap-pro/extension-snapshot' React Menus - import { BubbleMenu, FloatingMenu } from '@tiptap/react' + import { BubbleMenu, FloatingMenu } from '@tiptap/react/menus' Vue 3 Menus - import { BubbleMenu, FloatingMenu } from '@tiptap/vue-3' + import { BubbleMenu, FloatingMenu } from '@tiptap/vue-3/menus' Vue 2 Menus - import { BubbleMenu, FloatingMenu } from '@tiptap/vue-2' + import { BubbleMenu, FloatingMenu } from '@tiptap/vue-2/menus' ### [](https://tiptap.dev/docs/guides/upgrade-tiptap-v2#menu-systems) Menu Systems Tippy.js has been replaced with Floating UI for all floating elements. This affects: * @tiptap/extension-bubble-menu * @tiptap/extension-drag-handle * @tiptap/extension-drag-handle-react * @tiptap/extension-drag-handle-vue-2 * @tiptap/extension-drag-handle-vue-3 * @tiptap/extension-floating-menu * @tiptap/extension-mention * @tiptap/suggestion * @tiptap-pro/extension-emoji Example migration: // Before import { BubbleMenu } from '@tiptap/react' const menu =
, auto-generated on the first launch | | `api_secret` | API secret to use in the Authorization header, auto-generated on the first launch | | `allowed_origins` | Validates `Origin` headers against the provided values (comma separated), e.g., `https://test.tiptap.dev,https://*.tiptap.dev`; If not set, validation is disabled | | `authentication_disabled` | Set to `1` to disable authentication, `0` to enable (default: `0`) | | `webhook_url` | URL for receiving webhook callbacks | | `webhook_loader_url` | Optional webhook URL for initially loading documents. See [webhooks](https://tiptap.dev/docs/collaboration/core-concepts/webhooks#loader-webhook)
for more information. | | `webhook_version` | Version of the webhook | | `webhook_awareness` | Enable awareness webhooks for user activity, tracking `user.connected` and `user.disconnected` events (`1` for enabled, `0` for disabled) | | `webhook_log_errors_only` | Log only webhook errors; successful webhook logs are disabled | | `default_auto_versioning` | Set to `1` to enable auto versioning, `0` to disable (default: `0`) | | `default_auto_versioning_interval` | Interval for auto versioning in seconds (default: `30` seconds) | | `auto_versioning_all_fragments` | Set to `1` to make versioning listen for changes on any fragment/field of the doc (default is `0`, which will just watch the `default` fragment). This both affects auto versioning and manual versioning ; manual versioning will require `force=true` when this setting is `0`. Changing this requires the server to re-load the document to come into effect. | | `jwt_explicit_access` | Set to `1` to prevent document access when no "allowedDocumentNames" is set in the JWT. | | `skip_s3_health_check` | Set to `1` to turn off the s3 health check (on-prem only). This is useful if your s3 storage does not support `getCalledIdentity`. | | `name` | Instance name for identification | | `webhook_include_ydoc_state` | Set this to `1` to include the full yjs document in all document.saved webhooks | | `thread_authenticator` | Set this to `1` to enable the thread authenticator. Threads/comments will automatically be assigned with the user id from the JWT, and it will not be possible to edit or delete foreign threads. However, foreign threads can usually be resolved (except if disabled using the setting below) | | `commentonly_disallow_resolve_foreign_threads` | Set this to `1` to disallow resolving foreign threads when on comment-only connections. | | `webhook_include_fields` | Set this to `1` to include custom yjs fields in the webhook (see [webhooks](https://tiptap.dev/docs/collaboration/core-concepts/webhooks#custom-fields)
). | [](https://tiptap.dev/docs/collaboration/operations/configure#managing-settings-via-api) Managing settings via API ------------------------------------------------------------------------------------------------------------------ The collaboration platform offers a straightforward API for managing these settings. Replace `:key` with the setting key you wish to update. ### [](https://tiptap.dev/docs/collaboration/operations/configure#create-or-overwrite-settings) Create or overwrite settings Use this call to add or update settings: curl --location --request PUT 'https://YOUR_APP_ID.collab.tiptap.cloud/api/admin/settings/:key' \ --header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' --header 'Content-Type: text/plain' \ -d 'your value' ### [](https://tiptap.dev/docs/collaboration/operations/configure#list-current-settings) List current settings Use this call to retrieve a list of all current settings: curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/admin/settings' \ --header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' ### [](https://tiptap.dev/docs/collaboration/operations/configure#retrieve-a-specific-setting) Retrieve a specific setting Use this call to retrieve the value of a particular setting: curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/admin/settings/:key' \ --header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' ### [](https://tiptap.dev/docs/collaboration/operations/configure#delete-a-setting) Delete a setting Use this call to delete a setting: curl --location --request DELETE 'https://YOUR_APP_ID.collab.tiptap.cloud/api/admin/settings/:key' \ --header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' [](https://tiptap.dev/docs/collaboration/operations/configure#server-performance-metrics) Server performance metrics -------------------------------------------------------------------------------------------------------------------- Use the `/api/statistics` endpoint to gather server performance data, including total document count, peak concurrent connections, total connections over the last 30 days, and lifetime connection counts. Review the [metrics](https://tiptap.dev/docs/collaboration/operations/metrics) page for additional information. curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/statistics' \ --header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' [PreviouslyInject content](https://tiptap.dev/docs/collaboration/documents/content-injection) [Next upMetrics](https://tiptap.dev/docs/collaboration/operations/metrics) --- # Configure | Tiptap Comments Docs Comments are embedded within documents in the Collaboration Cloud. To enable comments, integrate the TiptapCollabProvider and configure your setup to support comment functionality. [](https://tiptap.dev/docs/comments/core-concepts/configure#provider) Provider ------------------------------------------------------------------------------ The `TiptapCollabProvider` instance Default: `null` const tiptapCollabProvider = new TiptapCollabProvider({ // your provider options }) Comments.configure({ provider: tiptapCollabProvider, }) [](https://tiptap.dev/docs/comments/core-concepts/configure#classes) Classes ---------------------------------------------------------------------------- The classes used for the threads. Default: { thread: 'tiptap-thread', threadInline: 'tiptap-thread--inline', threadBlock: 'tiptap-thread--block', threadHovered: 'tiptap-thread--hovered', threadSelected: 'tiptap-thread--selected', threadResolved: 'tiptap-thread--resolved', threadUnresolved: 'tiptap-thread--unresolved', } Comments.configure({ classes: { thread: 'my-thread', threadInline: 'my-thread-inline', threadBlock: 'my-thread-block', threadHovered: 'my-thread-hovered', threadSelected: 'my-thread-selected', threadResolved: 'my-thread-resolved', threadUnresolved: 'my-thread-unresolved', }, }) [](https://tiptap.dev/docs/comments/core-concepts/configure#onclickthread) onClickThread ---------------------------------------------------------------------------------------- A callback that is called when a thread is clicked. If the thread is clicked, the thread ID is passed to the callback. If no thread is clicked, `null` is passed. Default: `undefined` Comments.configure({ // ID can be a string or null onClickThread: (id) => console.log('Thread clicked', id), }) [](https://tiptap.dev/docs/comments/core-concepts/configure#deleteunreferencedthreads) deleteUnreferencedThreads ---------------------------------------------------------------------------------------------------------------- A boolean option that controls whether to delete threads not referenced in the document. By default, threads are marked as deleted when they are not referenced in a document anymore. This is useful for cleaning up threads that are no longer needed. However, if you want to keep the threads even if they are not referenced in the document, you can set this option to `false`. **Default:**: `true` Comments.configure({ // keep threads even if they are not referenced in the document deleteUnreferencedThreads: false, }) [](https://tiptap.dev/docs/comments/core-concepts/configure#uselegacywrapping) useLegacyWrapping ------------------------------------------------------------------------------------------------ ### Warning The new wrapping mechanism uses a different schema for threads on block nodes, which is not compatible with the previous wrapping behavior. If this is set to `false` without mapping existing thread nodes to the new schema, the threads content will be stripped from the document. A boolean option that controls whether to use the legacy wrapping mechanism for multi-line comments. We suggest for new implementations to set this to `false`, and existing integrations can stay on the previous behavior. This is only required for backwards compatibility with existing comments, and it will be removed in the future. The new wrapping mechanism is more flexible, allowing to wrap content more precise and supports mixed wrapping of inline and block nodes. **Default:** `true` Comments.configure({ // enable new flexible block wrapping useLegacyWrapping: false, }) [PreviouslyStyle threads](https://tiptap.dev/docs/comments/core-concepts/style-threads) [Next upThread authentication](https://tiptap.dev/docs/comments/core-concepts/thread-authentication) --- # Metrics | Tiptap Collaboration Docs The Tiptap Collaboration API offers several endpoints to access real-time statistics and health information for both the server and individual documents. A simplified version of the metrics is also available in the cloud dashboard. These endpoints help to troubleshoot issues, monitor server performance, or build analytics dashboards for insights into user interactions and system status. Integrating statistics into your monitoring systems allows you to proactively manage your collaboration environment's health. ### Review the postman collection Experiment with the REST API by visiting our [Postman Collection](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/request/33042171-1adccc70-772c-464a-8602-1303659f9af6) . [](https://tiptap.dev/docs/collaboration/operations/metrics#access-the-api) Access the API ------------------------------------------------------------------------------------------ The REST API is exposed directly from your Document server at your custom URL: https://YOUR_APP_ID.collab.tiptap.cloud/ ### [](https://tiptap.dev/docs/collaboration/operations/metrics#authentication) Authentication Authenticate your API requests by including your API secret in the `Authorization` header. You can find your API secret in the [settings](https://cloud.tiptap.dev/v2/configuration/document-server) of your Tiptap Cloud dashboard. ### [](https://tiptap.dev/docs/collaboration/operations/metrics#document-identifiers) Document identifiers If your document identifier contains a slash (`/`), encode it as `%2F`, e.g., using `encodeURIComponent`. [](https://tiptap.dev/docs/collaboration/operations/metrics#server-statistics-endpoint) Server statistics endpoint ------------------------------------------------------------------------------------------------------------------ This endpoint provides basic statistics about the Tiptap Collaboration server, offering insights into overall activity and usage metrics. GET /api/statistics ### Caution The total number of connections in the last 30 days and the lifetime connection count are presented as strings due to their internal representation as BigInt values. **Example:** Server statistics { "totalDocuments": 4, "totalConnections30d": "3", "maxConcurrentConnections30d": 3, "lifetimeConnections": "144", "currentConnectionsCount": 3, "currentLoadedDocumentsCount": 1, "openDocuments": ["testdocument"], "connectionsPerDocument": { "testdocument": 3 }, "version": "3.33.0" } [](https://tiptap.dev/docs/collaboration/operations/metrics#document-statistics-endpoint) Document statistics endpoint ---------------------------------------------------------------------------------------------------------------------- Retrieve statistics for a specific document by its identifier. Use this endpoint to monitor real-time user engagement with a document. GET /api/documents/:identifier/statistics **Example:** Statistics of a document named :identifier { "currentConnections": 2, "connectedIps": ["127.0.0.1", "10.100.1.23"] } [](https://tiptap.dev/docs/collaboration/operations/metrics#server-health-endpoint) Server health endpoint ---------------------------------------------------------------------------------------------------------- Use this call to check liveness, readiness, and cconnectivity to essential components like the database and Redis. GET /health **Example:** Issue with Redis HTTP 500: DB:ok REDIS:fail **Example:** No Redis detected HTTP 200: DB:ok REDIS:inactive [PreviouslyConfigure runtime](https://tiptap.dev/docs/collaboration/operations/configure) --- # Style threads | Tiptap Comments Docs To style threads in your Tiptap editor, we use decoration classes that are wrapped around the threads. Since threads can include block nodes, we have two types of decorations: one for inline threads, which are wrapped around the text, and one for block threads, which are wrapped around the block node. By default, the following css classes are used for the threads: .tiptap-thread {} // the thread class for any type of thread .tiptap-thread--inline {} // the thread class for inline threads .tiptap-thread--block {} // the thread class for block threads .tiptap-thread--hovered {} // the thread class for hovered threads .tiptap-thread--selected {} // the thread class for selected threads .tiptap-thread--resolved {} // the thread class for resolved threads .tiptap-thread--unresolved {} // the thread class for unresolved threads Those classes can also be overwritten by passing through the classes to the `CommentsKit` extension. const editor = new Editor({ ... extensions: [\ ...,\ CommentsKit.configure({\ classes: {\ thread: 'my-thread',\ threadInline: 'my-thread-inline',\ threadBlock: 'my-thread-block',\ threadHovered: 'my-thread-hovered',\ threadSelected: 'my-thread-selected',\ threadResolved: 'my-thread-resolved',\ threadUnresolved: 'my-thread-unresolved',\ },\ }),\ ] }) [](https://tiptap.dev/docs/comments/core-concepts/style-threads#handling-hover-events) Handling hover events ------------------------------------------------------------------------------------------------------------ Let's say you have a sidebar with a list of threads, and you want to highlight the thread currently hovered in your sidebar inside the editor. You can dispatch a transaction to the editor with the meta `threadMouseOver` or `threadMouseOut` to indicate which thread is currently hovered. const onHoverThread = (threadId) => { const { tr } = editor.state tr.setMeta('threadMouseOver', threadId) editor.view.dispatch(tr) } const onUnhoverThread = (threadId) => { const { tr } = editor.state tr.setMeta('threadMouseOut', threadId) editor.view.dispatch(tr) } ;
onHoverThread('123')} onMouseLeave={() => onUnhoverThread('123')}>
Thread 123
[PreviouslyManage threads](https://tiptap.dev/docs/comments/core-concepts/manage-threads)
[Next upConfigure](https://tiptap.dev/docs/comments/core-concepts/configure)
---
# Snapshot extension | Tiptap Editor Docs
Document history records every change to your content so you can roll back mistakes, audit edits, or branch a new draft from any point.
This page walks you through installation, configuration, and common tasks for the **History** extension.
### Public Demo
The editor content is shared across all demo visitors.
[](https://tiptap.dev/docs/collaboration/documents/snapshot#access-the-pro-registry)
Access the Pro registry
------------------------------------------------------------------------------------------------------------
The Version History extension is published in Tiptap’s private npm registry. Integrate the extension by following the [private registry guide](https://tiptap.dev/docs/guides/pro-extensions)
. If you already authenticated your Tiptap account you can go straight to [#Install](https://tiptap.dev/docs/collaboration/documents/snapshot#install)
.
[](https://tiptap.dev/docs/collaboration/documents/snapshot#install)
Install
----------------------------------------------------------------------------
npm install @tiptap-pro/extension-snapshot @hocuspocus/transformer
**Note**: The `@hocuspocus/transformer` package is required for transforming Y.js binary into Tiptap JSON. It also requires Y.js installed for collaboration. If you don't have it installed, run `npm install yjs` in your project. This should happen automatically if you use NPM (as it automatically resolves peer dependencies).
[](https://tiptap.dev/docs/collaboration/documents/snapshot#settings)
Settings
------------------------------------------------------------------------------
| Setting | Type | Default |
| --- | --- | --- |
| provider | `TiptapCollabProvider` | `null` |
| onUpdate | `function` | `() => {}` |
[](https://tiptap.dev/docs/collaboration/documents/snapshot#autoversioning)
Autoversioning
------------------------------------------------------------------------------------------
The autoversioning feature automatically creates new versions of your document at regular intervals. This ensures that you have a comprehensive change history without manual intervention.
You can enable this feature using the `enableAutoVersioning` command (default: disabled).
When you enable autoversioning, Tiptap creates new versions at regular intervals (30 seconds by default, only if the document has changed). This can create many versions, so you may want to increase the interval. To customize the interval, you can do the following:
// Set the interval (in seconds) between autoversions
provider.setAutoVersioningInterval(900)
provider.enableAutoVersioning()
provider.disableAutoVersioning()
[](https://tiptap.dev/docs/collaboration/documents/snapshot#revert-to-a-version)
Revert to a version
----------------------------------------------------------------------------------------------------
When you revert to a previous version:
1. If there are unsaved changes, Tiptap automatically creates a version to preserve those changes.
2. Tiptap creates a new version at the top of the history with the content from the version you select.
3. All users can continue working from this new version.
Note that reverting only affects the `default` fragment in the ydoc. When you revert the Tiptap content, the comments don't change (unless you specify a different `field` in the TiptapCollabProvider).
You can integrate the [compare snapshots](https://tiptap.dev/docs/collaboration/documents/snapshot-compare)
extension to highlight differences between versions, ensuring you choose the right version to restore.
[](https://tiptap.dev/docs/collaboration/documents/snapshot#storage)
Storage
----------------------------------------------------------------------------
| Key | Type | Description |
| --- | --- | --- |
| currentVersion | `number` | The current version. |
| lastSaved | `Date` | The last saved timestamp |
| latestVersion | `number` | The latest version. |
| provider | `TiptapCollabProvider` | The Collaboration provider instance |
| status | `string` | The status of the provider - can be `connecting`, `connected` or `disconnected` |
| synced | `boolean` | Is the version history synced with the server |
| versioningEnabled | `boolean` | Is versioning enabled |
| versions | `arrayThis is a radically reduced version of Tiptap. It has support for a document, with paragraphs and text. That’s it. It’s probably too much for real minimalists though.
The paragraph extension is not really required, but you need at least one node. Sure, that node can be something different.
`, }) returnThis is a radically reduced version of Tiptap. It has support for a document, with paragraphs and text. That’s it. It’s probably too much for real minimalists though.
The paragraph extension is not really required, but you need at least one node. Sure, that node can be something different.
`, }) // Connect to your Collaboration server useEffect(() => { const provider = new TiptapCollabProvider({ name: 'document.name', // Unique document identifier for syncing. This is your document name. appId: '7j9y6m10', // Your Cloud Dashboard AppID or `baseURL` for on-premises token: 'notoken', // Your JWT document: doc, }) }, []) returnThis is a radically reduced version of Tiptap. It has support for a document, with paragraphs and text. That’s it. It’s probably too much for real minimalists though.
The paragraph extension is not really required, but you need at least one node. Sure, that node can be something different.
`) } }, }) }, []) returntext
text
text
text
text
non-editable text
editable text
text
` consider to add a `data-type="my-custom-node"`.
### [](https://tiptap.dev/docs/editor/extensions/custom-extensions/node-views#parse-html)
Parse HTML
The same applies to restoring the content. You can configure what markup you expect, that can be something completely unrelated to the node view markup. It just needs to contain all the information you want to restore.
Attributes are automagically restored, if you registered them through [`addAttributes`](https://tiptap.dev/docs/editor/extensions/custom-extensions/extend-existing#attributes)
.
// Input: ` component with automatic context management and built-in subcomponents. Perfect for complex UIs with multiple child components. [Learn more →](https://tiptap.dev/docs/guides/react-composable-api)
To start using Tiptap, create a new component. Let's call it `Tiptap` and add the following code in `src/Tiptap.tsx`:
// src/Tiptap.tsx
import { useEditor, EditorContent } from '@tiptap/react'
import { FloatingMenu, BubbleMenu } from '@tiptap/react/menus'
import StarterKit from '@tiptap/starter-kit'
const Tiptap = () => {
const editor = useEditor({
extensions: [StarterKit], // define your extension array
content: 'This is the floating menu
This is the bubble menu
)
}
export default Tiptap
### [](https://tiptap.dev/docs/editor/getting-started/install/react#add-it-to-your-app)
Add it to your app
Finally, replace the content of `src/App.tsx` with our new `Tiptap` component.
import Tiptap from './Tiptap'
const App = () => {
return (
This is the floating menu
This is the bubble menu
)
}
export default Tiptap
### [](https://tiptap.dev/docs/editor/getting-started/install/react#consume-the-editor-context-in-child-components)
Consume the Editor context in child components
If you use the `EditorProvider` to set up your Tiptap editor, you can now access your editor instance from any child component using the `useCurrentEditor` hook.
import { useCurrentEditor } from '@tiptap/react'
const EditorJSONPreview = () => {
const { editor } = useCurrentEditor()
return ` component that simplifies editor setup with automatic context management and built-in subcomponents. This composable API is ideal for complex UIs with many child components. Learn more in the [React Composable API guide](https://tiptap.dev/docs/guides/react-composable-api)
.
[](https://tiptap.dev/docs/editor/getting-started/install/react#next-steps)
Next steps
--------------------------------------------------------------------------------------
* [Configure your editor](https://tiptap.dev/docs/editor/getting-started/configure)
* [Add styles to your editor](https://tiptap.dev/docs/editor/getting-started/style-editor)
* [Learn more about Tiptap concepts](https://tiptap.dev/docs/editor/core-concepts/introduction)
* [Learn how to persist the editor state](https://tiptap.dev/docs/editor/core-concepts/persistence)
* [Start building your own extensions](https://tiptap.dev/docs/editor/extensions/custom-extensions)
[PreviouslyVanilla JavaScript](https://tiptap.dev/docs/editor/getting-started/install/vanilla-javascript)
[Next upNext.js](https://tiptap.dev/docs/editor/getting-started/install/nextjs)
---
# Build AI features on the server
Build AI agents with document-editing superpowers on the server without a browser-based editor. The Server AI Toolkit provides flexible primitives and pre-built tools that enable your AI to read, edit, and manipulate Tiptap documents server-side.
### More details
For detailed information on installation, configuration, and comprehensive guides, please visit our [Server AI Toolkit feature page](https://tiptap.dev/docs/content-ai/capabilities/server-ai-toolkit/overview)
.
---
Hello World!
', // initial content }) return ( <>Hello World!
', // initial content }) // Memoize the provider value to avoid unnecessary re-renders const providerValue = useMemo(() => ({ editor }), [editor]) return ({JSON.stringify(editor.getJSON(), null, 2)}
}
**Important**: This won't work if you use the `useEditor` hook to setup your editor.
You should now see a pretty barebones example of Tiptap in your browser.
[](https://tiptap.dev/docs/editor/getting-started/install/react#reacting-to-editor-state-changes)
Reacting to Editor state changes
----------------------------------------------------------------------------------------------------------------------------------
To react to editor state changes, you can use the `useEditorState` hook from `@tiptap/react`. This hook can be used to fetch information from the editor state without causing re-renders on the editor component or it's children.
import { useEditorState } from '@tiptap/react'
function MyEditorComponent() {
// ... your editor setup code
const editorState = useEditorState({
editor,
// the selector function is used to select the state you want to react to
selector: ({ editor }) => {
if (!editor) return null;
return {
isEditable: editor.isEditable,
currentSelection: editor.state.selection,
currentContent: editor.getJSON(),
// you can add more state properties here e.g.:
// isBold: editor.isActive('bold'),
// isItalic: editor.isActive('italic'),
};
},
});
}
[](https://tiptap.dev/docs/editor/getting-started/install/react#use-ssr-with-react-and-tiptap)
Use SSR with React and Tiptap
----------------------------------------------------------------------------------------------------------------------------
Tiptap can be used with server-side rendering (SSR) in React applications. However, to ensure that the editor is only initialized on the client side, you need to use the `immediatelyRender` option when creating the editor instance to prevent it from rendering on the server.
Here is an example of how to set up Tiptap with SSR in a React component:
'use client'
import { useEditor, EditorContent } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'
export function MyEditor() {
const editor = useEditor({
extensions: [StarterKit],
content: 'Hello World!
', // Disable immediate rendering to prevent SSR issues immediatelyRender: false, }) if (!editor) { return null // Prevent rendering until the editor is initialized } return