---
title: "Paste Handler"
description: "Automatically clean and normalize pasted content from Microsoft Excel, Word, and Google Docs in your Tiptap editor."
canonical_url: "https://tiptap.dev/docs/editor/extensions/functionality/paste-handler"
---

# Paste Handler

Automatically clean and normalize pasted content from Microsoft Excel, Word, and Google Docs in your Tiptap editor.

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.

> **Interactive demo:** [PasteHandler](https://embed-pro.tiptap.dev/preview/Extensions/PasteHandler)

## Supported sources

| Source            | macOS Desktop | Windows Desktop |  Web (Browser)  |
| ----------------- | :-----------: | :-------------: | :-------------: |
| Microsoft Excel   |       ✓       |        ✓        |  ✓ (SharePoint) |
| Microsoft Word    |       ✓       |        ✓        |  ✓ (SharePoint) |
| Microsoft Outlook |       ✓       |        ✓        | ✓ (Outlook Web) |
| Google Docs       |       —       |        —        |        ✓        |
| Google Sheets     |       —       |        —        |        ✓        |

## Install

```bash
npm install @tiptap-pro/extension-paste-handler
```

## Usage

The extension requires no configuration. Just add it to your editor and it works automatically.

```js
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.