Events
BlockNote provides several event callbacks that allow you to respond to changes in the editor. These events are essential for building reactive applications and tracking user interactions.
Overview
The editor emits events for:
- Editor initialization - When the editor is ready for use
- Content changes - When blocks are inserted, updated, or deleted
- Selection changes - When the cursor position or selection changes
onCreate
The onCreate callback is called when the editor has been initialized and is ready for use.
editor.onCreate(() => {
console.log("Editor is ready for use");
// Initialize plugins, set up event listeners, etc.
});onChange
The onChange callback is called whenever the editor's content changes. This is the primary way to track modifications to the document.
editor.onChange((editor, { getChanges }) => {
console.log("Editor content changed");
// Get detailed information about what changed
const changes = getChanges();
console.log("Changes:", changes);
// Save content, update UI, etc.
});Understanding Changes
The getChanges() function returns detailed information about what blocks were affected:
/**
* The changes that occurred in the editor.
*/
type BlocksChanged = Array<
| {
// The affected block
block: Block;
// The source of the change
source: BlockChangeSource;
type: "insert" | "delete";
// Insert and delete changes don't have a previous block
prevBlock: undefined;
}
| {
// The affected block
block: Block;
// The source of the change
source: BlockChangeSource;
type: "update";
// The block before the update
prevBlock: Block;
}
>;Change Sources
Each change includes a source that indicates what triggered the modification:
type BlockChangeSource = {
type:
| "local" // Triggered by local user (default)
| "paste" // From paste operation
| "drop" // From drop operation
| "undo" // From undo operation
| "redo" // From redo operation
| "undo-redo" // From undo/redo operations
| "yjs-remote"; // From remote user (collaboration)
};onSelectionChange
The onSelectionChange callback is called whenever the editor's selection changes, including cursor movements and text selections.
editor.onSelectionChange((editor) => {
console.log("Selection changed");
// Get current selection information
const selection = editor.getSelection();
const textCursorPosition = editor.getTextCursorPosition();
console.log("Current selection:", selection);
console.log("Text cursor position:", textCursorPosition);
});Event Cleanup
All event callbacks return cleanup functions that you can call to remove the event listener:
// Set up event listeners
const cleanupOnChange = editor.onChange((editor, { getChanges }) => {
console.log("Content changed");
});
const cleanupOnSelection = editor.onSelectionChange((editor) => {
console.log("Selection changed");
});
// Later, clean up event listeners
cleanupOnChange();
cleanupOnSelection();