Extensions

BlockNote includes an extensions system which lets you expand the editor's behaviour. Extensions can include any of the following features:

• Keyboard shortcuts
• Input rules
• ProseMirror plugins
• TipTap extensions

Creating an extension

An extension is an instance of the BlockNoteExtension class. However, it's recommended for most use cases to create extensions using the createBlockNoteExtension function, rather than instanciating the class directly:

type BlockNoteExtensionOptions = {
  key: string;
  keyboardShortcuts?: Record<
    string,
    (ctx: { editor: BlockNoteEditor; }) => boolean
  >;
  inputRules?: {
    find: RegExp;
    replace: (props: {
      match: RegExpMatchArray;
      range: { from: number; to: number };
      editor: BlockNoteEditor;
    }) => PartialBlock | undefined;
  }[];
  plugins?: Plugin[];
  tiptapExtensions?: AnyExtension[];
}

const customBlockExtensionOptions: BlockNoteExtensionOptions = {
  key: "customBlockExtension",
  keyboardShortcuts: ...,
  inputRules: ...,
  plugins: ...,
  tiptapExtensions: ...,
}

const CustomExtension = createBlockNoteExtension(customBlockExtensionOptions);

Let's go over the options that can be passed into createBlockNoteExtension:

key: The name of the extension.

keyboardShortcuts?: Keyboard shortcuts can be used to run code when a key combination is pressed in the editor. The key names are the same as those used in the KeyboardEvent.key property. Takes an object which maps key name combinations (e.g. Meta+Shift+ArrowDown) to functions, which return true when the key press event is handled, or false otherwise. The functions have a single argument:

• ctx: An object containing the BlockNote editor instance.

inputRules?: Input rules update blocks when given regular expressions are found in them. Takes an array of objects. Each object has a find field for the regular expression to find, and a replace field, for a function that should run on a match. The function should return a PartialBlock which specifies how the block should be updated, or avoid updating it. It also has a single argument:

• props: An object containing the result of the regular expression match, a range for the Prosemirror position indices spanned by the match, and the BlockNote editor instance.

plugins?: An array of ProseMirror plugins.

tiptapExtensions?: An array of TipTap extensions.

Adding extensions to the editor

Extensions can be added to the editor on their own via the editor options or as part of custom blocks.

Adding directly to the editor

The extensions editor option takes an array of BlockNoteExtensions to be added to the editor:

const editor = useCreateBlockNote({
  extensions: [
    // Add extensions here:
    createBlockNoteExtension({ ... })
  ],
});

Adding to custom blocks

When creating a custom block using createReactBlockSpec, you can pass an array of BlockNoteExtensions to the third parameter:

const createCustomBlock = createReactBlockSpec(
  {
    // Block config
    ...
  },
  {
    // Block implementation
    ...
  }
  [
    // Add extensions here:
    createBlockNoteExtension({ ... })
  ],
});