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 also applies when importing HTML with tryParseHTMLToBlocks or inserting it with pasteHTML.

Word list numbering retains numeric starts, gaps, and restarts. Labels that BlockNote cannot represent, such as 1.2., stay as text instead of being removed.

Custom HTML preprocessing

Use the preprocessHTML editor option to replace the source normalization. The function receives the original HTML string and returns the HTML to parse. To extend the built-in handling, call defaultHTMLPreprocessor inside your function:

import { BlockNoteEditor, defaultHTMLPreprocessor } from "@blocknote/core";

const editor = BlockNoteEditor.create({
  preprocessHTML(html) {
    return defaultHTMLPreprocessor(html).replaceAll("Old label", "New label");
  },
});

Set preprocessHTML: false to disable Word and Google Docs normalization. Neither the default nor custom preprocessing runs for internal BlockNote clipboard HTML or pasteHTML(html, true). Preprocessing is not an HTML sanitizer.

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.