Paste Handler
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.
Known limitations
Safari clipboard strips table cell styling
When copying table cells from SharePoint Excel (or similar sources) in Safari and pasting into the editor, in-cell formatting like bold, italic, colors, and links is lost. Safari writes a stripped-down HTML payload to the clipboard that contains only the table structure and cell text — the styling information is removed before it reaches the editor.
This is a WebKit-level behavior and cannot be recovered by the paste handler. The same result occurs when pasting into other editors in Safari (e.g. SharePoint Word). Copies made from Chromium-based browsers or Firefox are not affected.