Tiptap

https://tiptap.dev/docs
Admin
Tiptap is a headless, framework-agnostic rich text editor based on ProseMirror, offering a...
Tokens:1,493,602
Snippets:12,259
Trust Score:9.9
Update:1 day ago
Show doc for...
Tokens:
Raw
### Installation commands for table rendering setups

Source: https://tiptap.dev/docs/conversion/content-types/structures-and-media/tables

Install the packages needed for each rendering option. The recommended setup uses @tiptap-pro/extension-convert-kit; the pagination setup adds @tiptap-pro/extension-pages-tablekit; the minimum setup uses @tiptap/extension-table.

```bash
# Recommended: ConvertKit (DOCX-aware, no pagination)
npm install @tiptap-pro/extension-convert-kit

# With pagination via the Pages extension
npm install @tiptap-pro/extension-pages-tablekit @tiptap-pro/extension-convert-kit

# Minimum: structure only, no DOCX cell formatting
npm install @tiptap/extension-table
```

--------------------------------

### Quick Start Commands for Local Development

Source: https://tiptap.dev/docs/hocuspocus/server/extensions/s3

Commands to set up the complete development environment, test S3 configuration, and start S3 playground examples.

```bash
# Set up complete development environment
npm run dev:setup

# Test S3 configuration
npm run dev:test-s3

# Start S3 playground examples
npm run playground:s3
```

--------------------------------

### Install Tiptap dependencies

Source: https://tiptap.dev/docs/editor/getting-started/install/svelte

Installs the core Tiptap packages and the starter kit, which includes common extensions. Also installs the bubble menu extension for the example.

```bash
npm install @tiptap/core @tiptap/pm @tiptap/starter-kit @tiptap/extension-bubble-menu
```

--------------------------------

### Minimal install of Selection extension

Source: https://tiptap.dev/docs/editor/extensions/functionality/selection

Import Selection from '@tiptap/extensions/selection' for a minimal setup.

```javascript
import { Editor } from '@tiptap/core'
import { Selection } from '@tiptap/extensions/selection'

new Editor({
  extensions: [Selection],
})
```

--------------------------------

### Minimal install with TableRow

Source: https://tiptap.dev/docs/editor/extensions/nodes/table-row

Use the TableRow extension directly for a minimal setup. This example shows importing TableRow from '@tiptap/extension-table/row' and adding it to the editor extensions.

```javascript
import { Editor } from '@tiptap/core'
import { TableRow } from '@tiptap/extension-table/row'

new Editor({
  extensions: [TableRow],
})
```

--------------------------------

### Install StarterKit with npm

Source: https://tiptap.dev/docs/editor/extensions/functionality/starterkit

Install the @tiptap/starter-kit package via npm.

```bash
npm install @tiptap/starter-kit
```

--------------------------------

### Anchor regex with ^ to match from start

Source: https://tiptap.dev/docs/editor/markdown/advanced-usage/custom-tokenizer

Always anchor your regex to the start of the string to avoid matching anywhere. The good example uses ^ to match from start, while the bad example can match anywhere.

```javascript
// ✅ Good - matches from start
/^==(.+?)==/

// ❌ Bad - can match anywhere
/==(.+?)==/
```

--------------------------------

### Install TextStyle and StarterKit

Source: https://tiptap.dev/docs/editor/extensions/marks/text-style

Install the @tiptap/extension-text-style and @tiptap/starter-kit packages via npm.

```bash
npm install @tiptap/extension-text-style @tiptap/starter-kit
```

--------------------------------

### Tokenizer start Function Example

Source: https://tiptap.dev/docs/editor/markdown/advanced-usage/custom-tokenizer

Shows the optional 'start' function that returns the index where the token might start, used as an optimization.

```javascript
{
  start: (src) => {
    // Find where '==' appears in the source
    return src.indexOf('==')
  },
  // ...
}
```

--------------------------------

### Install required npm packages for Tiptap and Hocuspocus

Source: https://tiptap.dev/docs/hocuspocus/provider/examples

Run this npm install command to install all required extensions for the Tiptap collaboration setup.

```bash
npm install @hocuspocus/provider @tiptap/core @tiptap/pm @tiptap/starter-kit @tiptap/extension-collaboration @tiptap/extension-collaboration-caret yjs y-prosemirror
```

--------------------------------

### Use StarterKit bundle

Source: https://tiptap.dev/docs/editor/getting-started/configure

Import StarterKit and pass it as the only extension. This bundles the most common extensions for a quick setup.

```javascript
import StarterKit from '@tiptap/starter-kit'

new Editor({
  extensions: [StarterKit],
})
```

--------------------------------

### Full setup with Markdown and ExportMarkdown extensions

Source: https://tiptap.dev/docs/conversion/export/markdown/editor-extension

Complete example showing how to configure the editor with the Markdown and ExportMarkdown extensions, including a download handler and usage of the exportMarkdown command with both extension-level and per-invocation callbacks.

```typescript
import { Markdown } from '@tiptap/markdown'
import { ExportMarkdown } from '@tiptap-pro/extension-export-markdown'

const editor = new Editor({
  extensions: [
    // Other extensions ...
    Markdown,
    ExportMarkdown.configure({
      onCompleteExport(result) {
        // Download the Markdown file
        const blob = new Blob([result], { type: 'text/markdown' })
        const url = URL.createObjectURL(blob)
        const a = document.createElement('a')

        a.href = url
        a.download = 'document.md'
        a.click()

        URL.revokeObjectURL(url)
      },
    }),
    // Other extensions ...
  ],
})

// Use the extension-level callback
editor.chain().exportMarkdown().run()

// Or override the callback for a specific export
editor
  .chain()
  .exportMarkdown({
    onCompleteExport(result) {
      // Custom handling, e.g. copy to clipboard
      navigator.clipboard.writeText(result)
    },
  })
  .run()
```

--------------------------------

### Correct setup: Mounting editor after provider sync

Source: https://tiptap.dev/docs/editor/extensions/functionality/uniqueid

This example shows the correct initialization order: initialize Y.Doc, start the collaboration provider, wait for the synced event, check if the collaborative document is empty, and then mount the editor with the correct content. It uses the onSynced callback to seed content only if the document is empty.

```javascript
import Collaboration from '@tiptap/extension-collaboration'
import { isChangeOrigin } from '@tiptap/extension-collaboration'
import { EditorContent, useEditor } from '@tiptap/react'
import { TiptapCollabProvider } from '@tiptap-pro/provider'
import { useEffect } from 'react'
import * as Y from 'yjs'

const doc = new Y.Doc()

export default () => {
  const editor = useEditor({
    extensions: [
      // ...other extensions
      UniqueID.configure({
        types: ['paragraph', 'heading'],
        filterTransaction: (transaction) => !isChangeOrigin(transaction),
      }),
      Collaboration.configure({
        document: doc,
      }),
    ],
    // Do not set content here — wait for sync
  })

  useEffect(() => {
    const provider = new TiptapCollabProvider({
      name: 'your-document-name',
      appId: 'YOUR_APP_ID',
      token: 'YOUR_JWT',
      document: doc,

      onSynced() {
        // Only seed content if the collaborative document is empty
        const isEmpty = doc.getXmlFragment('default').length === 0

        if (isEmpty && editor) {
          editor.commands.setContent(yourInitialContent)
        }
      },
    })
  }, [])

  return <EditorContent editor={editor} />
}
```

--------------------------------

### Initialize Notion-like Editor for New Projects

Source: https://tiptap.dev/docs/ui-components/templates/notion-like-editor

Run this command to initialize a new project with the Notion-like editor template. Requires a Tiptap account with an active subscription or trial.

```bash
npx @tiptap/cli@latest init notion-like-editor
```

--------------------------------

### Configure Tiptap extensions with StarterKit and custom extensions

Source: https://tiptap.dev/docs/guides/migrate-from-quill

Shows how to set up an Editor instance with a bundle of extensions, including StarterKit, Image, TextAlign, TextStyle, and Color. Demonstrates configuring options like inline images, base64 support, and applying TextAlign to heading and paragraph types.

```javascript
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],
    }),
  ],
})
```

--------------------------------

### DragHandle onElementDragStart prop example

Source: https://tiptap.dev/docs/editor/extensions/functionality/drag-handle-react

Called when the element starts to be dragged. Use it to add custom logic when dragging starts.

```jsx
<DragHandle
  onElementDragStart={(e: DragEvent) => {
    // do something when dragging starts
  }}
>
  <div>Drag Me!</div>
</DragHandle>
```

--------------------------------

### Install Tiptap dependencies for Vue 2

Source: https://tiptap.dev/docs/editor/getting-started/install/vue2

Installs the required packages: @tiptap/vue-2, @tiptap/pm, and @tiptap/starter-kit. After installation, start the project with 'npm run dev' and open http://localhost:8080.

```bash
npm install @tiptap/vue-2 @tiptap/pm @tiptap/starter-kit
```

--------------------------------

### Minimal install

Source: https://tiptap.dev/docs/editor/extensions/nodes/task-list

Import TaskList from the subpath '@tiptap/extension-list/task-list' for a minimal install.

```javascript
import { Editor } from '@tiptap/core'
import { TaskList } from '@tiptap/extension-list/task-list'

new Editor({
  extensions: [TaskList],
})
```

--------------------------------

### Example .env file

Source: https://tiptap.dev/docs/ai/ai-toolkit/install

Environment variables for TIPTAP_PRIVATE_KEY, TIPTAP_ENVIRONMENT_ID, and TIPTAP_CLOUD_AI_API_URL.

```bash
# ES256 private key (PKCS#8 PEM) from the Tiptap dashboard. Used to sign tokens server-side.
TIPTAP_PRIVATE_KEY=your-private-key-pem
# Environment ID from the Tiptap dashboard. Used as the `iss` claim when signing tokens.
TIPTAP_ENVIRONMENT_ID=your-environment-hash-id

# Base URL for the AI Toolkit API.
TIPTAP_CLOUD_AI_API_URL=https://api.tiptap.dev
```

--------------------------------

### Install Content Protection packages

Source: https://tiptap.dev/docs/composable-docs/content-protection/getting-started/overview

Install the required packages for Content Protection. Requires access to the pilot program and the private registry setup.

```bash
npm install @tiptap/core @tiptap/starter-kit @tiptap/y-tiptap yjs @tiptap-pro/extension-content-protection
```

--------------------------------

### Install @tiptap-pro/client-ai-toolkit-langchain

Source: https://tiptap.dev/docs/ai/ai-toolkit/client/agents/tools/langchain-js

Install the package using npm.

```bash
npm install @tiptap-pro/client-ai-toolkit-langchain
```

--------------------------------

### Get thread - curl example

Source: https://tiptap.dev/docs/comments/integrate/rest-api

Example curl command to fetch a specific thread. Replace YOUR_APP_ID, document_id, and thread_id with your actual values.

```bash
curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/{document_id}/threads/{thread_id}' \
--header 'Authorization: {{Authorization}}'
```

--------------------------------

### Install @tiptap-pro/client-ai-toolkit-openai

Source: https://tiptap.dev/docs/ai/ai-toolkit/client/agents/tools/openai

Install the package using npm.

```bash
npm install @tiptap-pro/client-ai-toolkit-openai
```

--------------------------------

### Get document field with curl

Source: https://tiptap.dev/docs/collaboration/documents/content-injection

Example curl request to get a field named `configuration` of type `map`. Replace `YOUR_APP_ID` and `YOUR_JWT` with your credentials.

```bash
curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/my-doc/fields?field=configuration&type=map' \
--header 'Authorization: Bearer YOUR_JWT'
```

--------------------------------

### init

Source: https://tiptap.dev/docs/ui-components/getting-started/cli

Initializes your project and installs dependencies. In an empty directory it scaffolds a new Vite or Next.js project; in an existing project it configures it. Components are copied into your components/ folder.

```APIDOC
## init

### Description
Initialize your project and install dependencies. This command sets up your project configuration and adds any specified components as editable source files.

### Usage
```
npx @tiptap/cli@latest init
```

### Arguments
- `components` - The components to add.

### Options
```
Usage: @tiptap/cli@latest init [options] [components...]

Options:
-f, --framework <framework>   The framework to use (next, vite)
-c, --cwd <cwd>               The working directory (defaults to current directory)
-s, --silent                  Mute output
--src-dir                     Use the src directory when creating a new project
```
```

--------------------------------

### Get threads - curl example

Source: https://tiptap.dev/docs/comments/integrate/rest-api

Example curl command to list all threads for a document. Replace YOUR_APP_ID and document_id with your actual values. Requires an Authorization header.

```bash
curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/{document_id}/threads' \
--header 'Authorization: {{Authorization}}'
```

--------------------------------

### Install Notion-like Editor for Existing Projects

Source: https://tiptap.dev/docs/ui-components/templates/notion-like-editor

Run this command in an existing project to add the Notion-like editor template. Requires a Tiptap account with an active subscription or trial.

```bash
npx @tiptap/cli@latest add notion-like-editor
```

--------------------------------

### Install @tiptap-pro/extension-export-docx

Source: https://tiptap.dev/docs/conversion/export/docx/editor-extension

Install the DOCX Export extension package from Tiptap's private npm registry. Requires following the private registry guide first.

```bash
npm i @tiptap-pro/extension-export-docx
```

--------------------------------

### Install Tiptap dependencies

Source: https://tiptap.dev/docs/guides/migrate-from-ckeditor4

Command to install the core Tiptap packages and the StarterKit extension.

```bash
npm install @tiptap/core @tiptap/starter-kit
```

--------------------------------

### Minimal install

Source: https://tiptap.dev/docs/editor/extensions/nodes/bullet-list

Import BulletList from the subpath '@tiptap/extension-list/bullet-list' for a minimal install.

```javascript
import { Editor } from '@tiptap/core'
import { BulletList } from '@tiptap/extension-list/bullet-list'

new Editor({
  extensions: [BulletList],
})
```

--------------------------------

### Install @tiptap-pro/client-ai-toolkit-anthropic

Source: https://tiptap.dev/docs/ai/ai-toolkit/client/agents/tools/anthropic

Install the package using npm.

```bash
npm install @tiptap-pro/client-ai-toolkit-anthropic
```

--------------------------------

### getMarkdownRange example

Source: https://tiptap.dev/docs/ai/ai-toolkit/client/api-reference/read-the-document

Returns Markdown content from a specified range. Requires the Tiptap Markdown extension to be installed and configured. The example reads Markdown from position 0 to 100.

```javascript
// Read the Markdown of the content from position 0 to 100
const snippet = toolkit.getMarkdownRange({ from: 0, to: 100 })
```

--------------------------------

### Install @tiptap-pro/compare

Source: https://tiptap.dev/docs/compare/getting-started/overview

Install the Compare add-on package after gaining access and configuring your package manager.

```bash
npm install @tiptap-pro/compare
```

--------------------------------

### Use TableCell with TableKit extension

Source: https://tiptap.dev/docs/editor/extensions/nodes/table-cell

The TableCell extension is installed by default with the TableKit extension, so you don't need to install it separately. This example shows how to set up an Editor with TableKit.

```javascript
import { Editor } from '@tiptap/core'
import { TableKit } from '@tiptap/extension-table'

new Editor({
  extensions: [TableKit],
})
```

--------------------------------

### Tiptap CLI init options

Source: https://tiptap.dev/docs/ui-components/getting-started/cli

Lists the options available for the init command, including framework, working directory, silent mode, and src-dir.

```bash
Usage: @tiptap/cli@latest init [options] [components...]

Options:
-f, --framework <framework>   The framework to use (next, vite)
-c, --cwd <cwd>               The working directory (defaults to current directory)
-s, --silent                  Mute output
--src-dir                     Use the src directory when creating a new project
```

--------------------------------

### Install @tiptap-pro/extension-comments via npm

Source: https://tiptap.dev/docs/comments/getting-started/install

Install the Comments extension from Tiptap's private npm registry. Requires access to the private registry as described in the private registry guide.

```bash
npm install @tiptap-pro/extension-comments
```

--------------------------------

### Minimal install for LineHeight

Source: https://tiptap.dev/docs/editor/extensions/functionality/line-height

Import LineHeight directly from the line-height subpath for a minimal setup.

```javascript
import { Editor } from '@tiptap/core'
import { LineHeight } from '@tiptap/extension-text-style/line-height'

new Editor({
  extensions: [LineHeight],
})
```

--------------------------------

### Start the dev server

Source: https://tiptap.dev/docs/ui-components/install/vite

Run the development server to see the editor in action.

```bash
npm run dev
```

--------------------------------

### Get project info with Tiptap CLI

Source: https://tiptap.dev/docs/ui-components/getting-started/cli

Displays information about your project configuration and setup.

```bash
npx @tiptap/cli@latest info
```

--------------------------------

### Install @tiptap/extension-mathematics and katex

Source: https://tiptap.dev/docs/conversion/content-types/structures-and-media/math-equations

Install the required packages for math support. The Mathematics extension is not included in StarterKit, and katex version ^0.16.4 is needed for rendering.

```bash
npm install @tiptap/extension-mathematics katex
```

--------------------------------

### Initialize a new Tiptap project

Source: https://tiptap.dev/docs/ui-components/components/drag-context-menu

Run this command to initialize a new project with the Tiptap CLI. During setup, select your preferred framework and choose 'No' when prompted to add a template or UI components.

```bash
npx @tiptap/cli@latest init
```

--------------------------------

### Minimal install of Dropcursor extension

Source: https://tiptap.dev/docs/editor/extensions/functionality/dropcursor

Import the Dropcursor extension directly from '@tiptap/extensions/dropcursor' for a minimal setup.

```javascript
import { Editor } from '@tiptap/core'
import { Dropcursor } from '@tiptap/extensions/dropcursor'

new Editor({
  extensions: [Dropcursor],
})
```

--------------------------------

### useFontFamilyCombobox() usage example

Source: https://tiptap.dev/docs/ui-components/components/font-family-combobox

Shows how to use the hook to get state and actions for a custom font picker. The example destructures isVisible, triggerLabel, selectFont, selectDefault, and filterFonts, and demonstrates filtering fonts with a query.

```javascript
function MyFontPicker() {
  const { isVisible, triggerLabel, selectFont, selectDefault, filterFonts } = useFontFamilyCombobox(
    { editor, hideWhenUnavailable: true },
  )

  if (!isVisible) return null

  const results = filterFonts('geo') // ranked matches for a search query
  // …render your own UI using selectFont(font) / selectDefault()
}
```

--------------------------------

### Initialize Simple Editor Template for new projects

Source: https://tiptap.dev/docs/ui-components/templates/simple-editor

Run this command to initialize a new project with the Simple Editor template. It uses the Tiptap CLI.

```bash
npx @tiptap/cli@latest init simple-editor
```

--------------------------------

### Initialize new project with DOCX template

Source: https://tiptap.dev/docs/ui-components/templates/docx-editor

Run this command to create a new project with the DOCX editor template. Requires a Tiptap account with an active subscription or trial.

```bash
npx @tiptap/cli@latest init docx
```

--------------------------------

### Minimal install with FontFamily only

Source: https://tiptap.dev/docs/editor/extensions/functionality/fontfamily

Import FontFamily directly from the subpath '@tiptap/extension-text-style/font-family' for a minimal setup without TextStyle.

```javascript
import { Editor } from '@tiptap/core'
import { FontFamily } from '@tiptap/extension-text-style/font-family'

new Editor({
  extensions: [FontFamily],
})
```

--------------------------------

### Basic Setup: Add Markdown extension to editor

Source: https://tiptap.dev/docs/editor/markdown/getting-started/installation

Imports Editor, StarterKit, and Markdown, then creates an editor instance with the Markdown extension. The editor is attached to the #editor element and initial content is HTML.

```javascript
import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { Markdown } from '@tiptap/markdown'

const editor = new Editor({
  element: document.querySelector('#editor'),
  extensions: [StarterKit, Markdown],
  content: '<p>Hello World!</p>',
})
```

--------------------------------

### Setup with TextStyleKit

Source: https://tiptap.dev/docs/editor/extensions/functionality/background-color

The Background Color extension is included by default in the TextStyleKit, so you can use it without separate installation.

```javascript
import { Editor } from '@tiptap/core'
import { TextStyleKit } from '@tiptap/extension-text-style'

new Editor({
  extensions: [TextStyleKit],
})
```
Tokens:
Raw