Paste Handler
Available in Team plan
The PasteHandler extension intelligently transforms pasted HTML to ensure compatibility with content from external sources. It runs a series of transformations on pasted content to clean up source-specific formatting artifacts while preserving user intent.
Supported sources
| Source | macOS Desktop | Windows Desktop | Web (Browser) |
|---|---|---|---|
| Microsoft Excel | ✓ | ✓ | ✓ (SharePoint) |
| Microsoft Word | ✓ | ✓ | ✓ (SharePoint) |
| Microsoft Outlook | ✓ | ✓ | ✓ (Outlook Web) |
| Google Docs | — | — | ✓ |
| Google Sheets | — | — | ✓ |
Install
npm install @tiptap-pro/extension-paste-handlerUsage
The extension requires no configuration. Just add it to your editor and it works automatically.
import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import PasteHandler from '@tiptap-pro/extension-paste-handler'
const editor = new Editor({
extensions: [
StarterKit,
PasteHandler,
],
})What it handles
The extension applies a series of transformations to pasted HTML, executed in a specific order:
| Transformation | Description |
|---|---|
| CSS class resolution | Resolves class-based CSS formatting (e.g. from Excel) to inline styles |
| Office markup cleanup | Removes Microsoft Office-specific elements and properties like <o:p> tags and mso-* styles |
| Bookmark removal | Strips Word bookmark markers and empty bookmark anchors |
| Table cell text styles | Ensures text formatting in table cells is properly recognized by the editor |
| Background color conversion | Converts background-color styles to highlight marks for the Highlight extension |
| ARIA heading conversion | Transforms ARIA heading elements (from SharePoint Word) to semantic HTML headings |
| Horizontal rule detection | Detects text-based horizontal rules (e.g. from Google Docs) and converts them to <hr> elements |
| Soft line break merging | Merges consecutive zero-margin paragraphs (from Google Docs) into proper line breaks |
| Nested list reconstruction | Rebuilds flat list structures (from SharePoint) into properly nested lists |
| Ordered list normalization | Removes inline list-style-type to let your editor's CSS control list styling |
| Orphan break cleanup | Removes stray <br> tags between block elements that cause unwanted spacing |
Error handling
If any transformation fails, the extension gracefully falls back to the original pasted HTML to ensure paste functionality is never broken.