BlockNote

Minimal Setup

import "@blocknote/core/fonts/inter.css";
import { BlockNoteView } from "@blocknote/mantine";
import "@blocknote/mantine/style.css";
import { useCreateBlockNote } from "@blocknote/react";

export default function App() {
  const editor = useCreateBlockNote();
  return <BlockNoteView editor={editor} />;
}

Next.js: BlockNote is client-only. Use "use client" directive + dynamic(() => import("./Editor"), { ssr: false }). Disable reactStrictMode for React 19 / Next 15.

Core API Quick Reference

useCreateBlockNote

function useCreateBlockNote(
  options?: BlockNoteEditorOptions,
  deps?: React.DependencyList,
): BlockNoteEditor;

Key options:

• initialContent: PartialBlock[] -- starting document content
• schema: BlockNoteSchema -- custom blocks/inline content/styles
• uploadFile: (file: File) => Promise<string> -- file upload handler
• resolveFileUrl: (url: string) => Promise<string> -- resolve indirect file URLs
• pasteHandler: PasteHandler -- custom paste behavior
• dictionary: Dictionary -- i18n locale object
• collaboration: { provider, fragment, user, showCursorLabels } -- Yjs real-time collab
• domAttributes: Record<string, Record<string, string>> -- custom DOM attrs
• extensions: Extension[] -- custom extensions
• tables: { splitCells?, cellBackgroundColor?, cellTextColor?, headers? } -- table features

BlockNoteView Props

BlockNoteView is uncontrolled -- pass initial content via useCreateBlockNote({ initialContent }), not as a prop.

Document Structure

type Block = {
  id: string;
  type: string;
  props: Record<string, boolean | number | string>;
  content: InlineContent[] | TableContent | undefined;
  children: Block[];
};

type InlineContent = StyledText | Link | CustomInlineContent;

type StyledText = {
  type: "text";
  text: string;
  styles: Styles;
};

type Link = {
  type: "link";
  content: StyledText[];
  href: string;
};

// Default styles
type Styles = Partial<{
  bold: boolean;       // default false
  italic: boolean;     // default false
  underline: boolean;  // default false
  strike: boolean;     // default false
  code: boolean;       // default false
  textColor: string;   // default "default"
  backgroundColor: string; // default "default"
}>;

All blocks share DefaultProps:

type DefaultProps = {
  backgroundColor: string;     // "default"
  textColor: string;           // "default"
  textAlignment: "left" | "center" | "right" | "justify"; // "left"
};

Editor Manipulation Methods

// Reading
editor.document                              // Block[] snapshot
editor.getBlock(id): Block | undefined
editor.getPrevBlock(id): Block | undefined
editor.getNextBlock(id): Block | undefined
editor.getParentBlock(id): Block | undefined
editor.forEachBlock(cb: (block) => boolean, reverse?: boolean): void

// Creating
editor.insertBlocks(blocks: PartialBlock[], ref: BlockIdentifier, placement?: "before" | "after"): void

// Updating
editor.updateBlock(id: BlockIdentifier, update: PartialBlock): void

// Removing
editor.removeBlocks(ids: BlockIdentifier[]): void

// Replacing
editor.replaceBlocks(toRemove: BlockIdentifier[], toInsert: PartialBlock[]): void

// Reordering
editor.moveBlocksUp(): void
editor.moveBlocksDown(): void
editor.canNestBlock(): boolean
editor.nestBlock(): void
editor.canUnnestBlock(): boolean
editor.unnestBlock(): void

// Transactions (group for single undo/redo)
editor.transact(() => { /* multiple operations */ }): void

// Cursor & Selection
editor.getTextCursorPosition(): TextCursorPosition
editor.setTextCursorPosition(target: BlockIdentifier, placement?: "start" | "end"): void
editor.getSelection(): Selection | undefined
editor.setSelection(start: BlockIdentifier, end: BlockIdentifier): void

// Inline Content
editor.insertInlineContent(content: PartialInlineContent): void
editor.getSelectedText(): string
editor.getActiveStyles(): Styles
editor.getSelectedLinkUrl(): string | undefined
editor.addStyles(styles: Styles): void
editor.removeStyles(styles: Styles): void
editor.toggleStyles(styles: Styles): void
editor.createLink(url: string, text?: string): void

// Paste
editor.pasteHTML(html: string, raw?: boolean): void
editor.pasteText(text: string): void
editor.pasteMarkdown(markdown: string): void

// Misc
editor.focus(): void
editor.isFocused(): boolean
editor.undo(): void
editor.redo(): void
editor.isEditable: boolean  // set to toggle read-only
editor.openSuggestionMenu(trigger: string): void

Format Conversion

// Export (lossy)
editor.blocksToHTMLLossy(blocks?: Block[]): string
editor.blocksToMarkdownLossy(blocks?: Block[]): string

// Export (lossless, BlockNote-native HTML)
editor.blocksToFullHTML(blocks?: Block[]): string

// Import
editor.tryParseHTMLToBlocks(html: string): Block[]
editor.tryParseMarkdownToBlocks(markdown: string): Block[]

Best practice: Store documents as JSON.stringify(editor.document) for zero data loss.

Events

editor.onChange((editor, { getChanges }) => { ... }): () => void
editor.onBeforeChange(({ getChanges, tr }) => boolean | void): () => void
editor.onSelectionChange((editor) => { ... }): () => void
editor.onMount(() => { ... }): () => void
editor.onUnmount(() => { ... }): () => void

Change types: "insert", "delete", "update", "move". Each change has a source: "local", "paste", "drop", "undo", "redo", "undo-redo", "yjs-remote".

All event callbacks return cleanup functions.

Built-in Block Types Summary

For full type definitions and all prop defaults, see references/api-reference.md.

Custom Schema Creation

import { BlockNoteSchema, defaultBlockSpecs, defaultInlineContentSpecs, defaultStyleSpecs } from "@blocknote/core";

// Method 1: Extend defaults
const schema = BlockNoteSchema.create().extend({
  blockSpecs: { myBlock: MyCustomBlock },
  inlineContentSpecs: { mention: Mention },
  styleSpecs: { font: Font },
});

// Method 2: From scratch (only includes what you specify)
const schema = BlockNoteSchema.create({
  blockSpecs: { ...defaultBlockSpecs, myBlock: MyCustomBlock },
  inlineContentSpecs: { ...defaultInlineContentSpecs, mention: Mention },
  styleSpecs: { ...defaultStyleSpecs, font: Font },
});

const editor = useCreateBlockNote({ schema });

For custom block/inline content/style creation APIs, see references/custom-schemas.md.

References Guide