Paste Handling

BlockNote, by default, attempts to paste content in the following order:

• VS Code compatible content
• Files
• BlockNote HTML
• Markdown
• HTML
• Plain text

You can change the default paste behavior by providing a custom paste handler, which will give you full control over how pasted content is inserted into the editor.

Word and Google Docs

BlockNote automatically converts Microsoft Word list paragraphs into nested lists, removes Word paragraph-end placeholders, and preserves blank paragraphs copied from Google Docs. This applies to external HTML pasted from the clipboard.

This is a best-effort conversion into BlockNote's block types, not exact source formatting preservation. Unsupported list labels, such as iv. or 1.2., stay as text instead of being removed.

To replace this behavior, use a custom pasteHandler and handle the HTML before calling editor.pasteHTML. Calling defaultPasteHandler keeps the built-in normalization. Internal BlockNote clipboard content bypasses this normalization.

pasteHandler option

The pasteHandler option is a function that receives the following arguments:

type PasteHandler = (context: {
  event: ClipboardEvent;
  editor: BlockNoteEditor;
  defaultPasteHandler: (context?: {
    prioritizeMarkdownOverHTML?: boolean;
    plainTextAsMarkdown?: boolean;
  }) => boolean;
}) => boolean;

• event: The paste event.
• editor: The current editor instance.
• defaultPasteHandler: The default paste handler. If you only need to customize the paste behavior a little bit, you can fall back on the default paste handler.

The defaultPasteHandler function can be called with the following options:

• prioritizeMarkdownOverHTML: Whether to prioritize Markdown content in text/plain over text/html when pasting from the clipboard.
• plainTextAsMarkdown: Whether to interpret plain text as markdown and paste that as rich text or to paste the text directly into the editor.

Custom Paste Handler

You can also provide your own paste handler by providing a function to the pasteHandler option.

In this example, we handle the paste event if the clipboard data contains text/my-custom-format. If we don't handle the paste event, we call the default paste handler to do the default behavior.

const editor = new BlockNoteEditor({
  pasteHandler: ({ event, editor, defaultPasteHandler }) => {
    if (event.clipboardData?.types.includes("text/my-custom-format")) {
      // You can do any custom logic here, for example you could transform the clipboard data before pasting it
      const markdown = customToMarkdown(
        event.clipboardData.getData("text/my-custom-format"),
      );

      // The editor is able paste markdown (`pasteMarkdown`), HTML (`pasteHTML`), or plain text (`pasteText`)
      editor.pasteMarkdown(markdown);
      // We handled the paste event, so return true, returning false will cancel the paste event
      return true;
    }

    // If we didn't handle the paste event, call the default paste handler to do the default behavior
    return defaultPasteHandler();
  },
});

See an example of this in the Custom Paste Handler example.