refactor: move all blocks to use the custom blocks API #1904

nperez0111 · 2025-08-01T08:11:05Z

Might want to address in the future: #1919 (comment)

TODO:

vercel · 2025-08-01T08:11:10Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
blocknote	Error		Sep 1, 2025 4:07pm
blocknote-website	Error		Sep 1, 2025 4:07pm

matthewlipski

Looks good! Just kind of glanced over everything for now with mostly questions

matthewlipski · 2025-08-01T14:53:22Z

packages/core/src/schema/blocks/createSpec.ts

@@ -111,6 +117,37 @@ export function getParseRules(

        return props;
      },
+      getContent:


Do you think it would be possible to return the content element in the parse function, instead of having a separate parseContent? Because I know they're split in the PM API, but I think it would be more intuitive to merge them into 1 function for the custom block API.

Yea, I thought about this too. Right now, it is pretty easy to do a mapping of HTML -> BlockNote node. But what isn't clear is how to do that mapping for parsing of inner content. We've been going through Prosemirror DOMParser & doing this low-level. I tried a couple of different approaches to do it more high-level & couldn't figure out anything satisfactory.

So, I went with the approach of a "good default", (merge paragraphs to preserve content within the parsed element), and left the rest as an exercise for later. I think what will be useful in this is when we separate out the HTML parsing & exporting from the editor instance, then maybe it will be easier for consumers to parse HTML into the shape that they need 🤷. I marked it as an "advanced" API so that it is clear we are not happy with it. Right now the only time that any of the default blocks need to use parseContent is the list item types, because we added better handling of HTML -> list items.

matthewlipski · 2025-08-01T14:55:29Z

packages/core/src/blks/NumberedListItem/IndexingPlugin.ts

+      );
+
+      if (existingDecorations.length === 0) {
+        // Create a widget decoration to display the index


Comment needs updating

matthewlipski · 2025-08-01T14:59:40Z

packages/core/src/blocks/defaultBlockTypeGuards.ts

@@ -32,8 +32,8 @@ export function checkDefaultBlockTypeInSchema<
  S
 > {
  return (
-    blockType in editor.schema.blockSchema &&
-    editor.schema.blockSchema[blockType] === defaultBlockSchema[blockType]
+    blockType in editor.schema.blockSchema //&&


This is just a temp change while the updated blocks are not yet in the default schema right?

matthewlipski · 2025-08-01T15:03:14Z

packages/core/src/editor/BlockNoteEditor.ts

+              name: key,
+              priority: ext.priority,
+              addProseMirrorPlugins: () => ext.plugins,
+              // TODO maybe collect all input rules from all extensions into one plugin


I think it's more intuitive to keep logic for a block/extension within the same extension

matthewlipski · 2025-08-01T15:03:49Z

packages/core/src/editor/BlockNoteSchema.ts

@@ -105,3 +105,6 @@ export class BlockNoteSchema<
    this.styleSchema = getStyleSchemaFromSpecs(this.styleSpecs) as any;
  }
 }
+


TODO: Remove?

matthewlipski · 2025-08-01T15:08:01Z

packages/core/src/schema/blocks/types.ts

@@ -21,6 +21,8 @@ export type BlockNoteDOMAttributes = Partial<{
  [DOMElement in BlockNoteDOMElement]: Record<string, string>;
 }>;

+// TODO we should remove FileBlockConfig, and only use BlockConfig
+// Ideally something like this would be represented via `groups: ["file"]` or similar


Could we add a file field to the new meta property in the config?

I'm not sure on this. It feels wrong to me that files are somehow different. Like why is there a file field & not a listItem field? I am not in favor of adding more properties than needed, since it adds complexity to each custom block that people can add.

I don't fully understand why this is even required at this point

packages/core/src/util/topo-sort.ts

YousefED

nice. posted some first thoughts / questions!

YousefED · 2025-08-04T06:23:18Z

packages/core/src/blks/BulletListItem/definition.ts

+            return true;
+          }),
+      },
+      inputRules: [


cool that there's a BN-style API for this. Can we do the same for keyboardshortcuts you think?

I thought about what that would look like for keyboard shortcuts, but the problem is that keyboard shortcuts can sort of just do anything. Some usecases I thought of were:

bringing up some menu items

triggering some action (e.g. stop AI generation)

inserting a new element

modifying an existing block

These sorts of cases are too disparate to really "unify" into a sensible API. Fundamental tension between composability & centralization.

YousefED · 2025-08-04T06:27:55Z

packages/core/src/schema/blocks/playground.ts

+   * Advanced parsing function that controls how content within the block is parsed.
+   * This is not recommended to use, and is only useful for advanced use cases.
+   */
+  parseContent?: (options: { el: HTMLElement; schema: Schema }) => Fragment;


would be nice to do this in a way that we don't expose Prosemirror APIs (i.e.: not expose Fragment) - not sure this is possible

#1904 (comment)

Yea I couldn't find a great way to do this. Especially given that the only case that really needs this are list items

YousefED · 2025-08-04T06:29:18Z

packages/core/src/schema/blocks/playground.ts

+     * The BlockNote editor instance
+     */
+    editor: BlockNoteEditor<Record<TName, BlockConfig<TName, TProps>>>,
+  ) => {


These functions (dom / contentDOM / ignoreMutation) are very prosemirror specific. For now out of scope (as they're also in the existing API and this PR is about moving blocks over), but don't think this is ideal

Yep, agreed, but not looking to rock that boat right now

YousefED · 2025-08-04T06:40:11Z

packages/core/src/blks/BulletListItem/definition.ts

+    },
+  }),
+  () => [
+    createBlockNoteExtension({


What was the reasoning again to define keyboardshortcuts / inputrules in a separate argument + createBlockNoteExtension?

This introduces keyboard shortcuts & inputrules to the extension API because we didn't have a way of doing them before.

I considered exposing them to both APIs (e.g. a custom block has an input rule API & so does the extension API), but that only added complexity.

Allowing extensions to be included to the block API is useful in that some things may require an extension to function (e.g. code block syntax highlighting, numbered list decorations).

YousefED · 2025-09-01T08:46:10Z

examples/06-custom-schema/react-custom-blocks/src/App.tsx

@@ -41,8 +41,8 @@ export const alertBlock = createReactBlockSpec(
      textAlignment: defaultProps.textAlignment,
      textColor: defaultProps.textColor,
      type: {
-        default: "warning",
-        values: ["warning", "error", "info", "success"],
+        default: "warning" as const,


is the as const necessary now where before it wasn't? it's not ideal imo (the as const syntax is probably not understood by basic TS devs, so if we can avoid it that'd be better ofc)

It was necessary before too, this example just was not typed properly from the get go. So it isn't worse, it just isn't any better. TS infers an object within an object like this by default. I think we can just as const the whole object though so it can be simpler.

packages/xl-multi-column/src/blocks/schema.ts

YousefED · 2025-09-01T08:59:22Z

packages/xl-odt-exporter/src/odt/defaultSchema/blocks.tsx

-    typeof pageBreakSchema.blockSchema &
-    typeof multiColumnSchema.blockSchema,
+  DefaultBlockSchema & {
+    pageBreak: ReturnType<typeof createPageBreakBlockConfig>;


minor: would be nice to have this consistent between pagebreak / multicolumn

…e block examples

YousefED · 2025-09-01T09:49:41Z

packages/core/src/blocks/Paragraph/block.ts

+      meta: {
+        isolating: false,
+      },
+    }) as const,


fyi, as we now use createBlockSpec we use custom NodeViews for all blocks, right?

I asked Marijn a long time ago if this can have negative consequences; https://discuss.prosemirror.net/t/pros-cons-of-custom-nodeviews-vs-regular-nodespec/5999

Do we need specific update logic? what's the default update logic for non-nodeview nodes?

I spent a good amount of time looking into this.

This is the default implementation of a NodeView's update method, It checks that the node type is the same as the currently rendered one - and only if it isn't, will it recreate the node view.

I think we should hold off on this until we have an actual use case, before trying to come up with a node view that does anything more than this. You would need this method for a nodeview which is carrying state that you may want to preserve (if the node is updating often). In the default blocks, this would really only be the code block extension to save a re-instantiation of the highlighter in specific situations. But, if we don't update when we should have, the nodeview can become out of sync with the document state.

So, I think we can safely hold off on this for now & come back to it when it is a problem

packages/core/src/schema/blocks/types.ts

packages/core/src/blocks/PageBreak/getPageBreakSlashMenuItems.ts

YousefED · 2025-09-01T10:00:46Z

packages/core/src/blocks/PageBreak/block.ts

+    render() {
+      const pageBreak = document.createElement("div");
+
+      pageBreak.className = "bn-page-break";


do we need both bn-page-break and data-page-break?

I'll leave that decision to @matthewlipski

YousefED · 2025-09-01T10:04:44Z

packages/core/src/blocks/Quote/block.ts

+  },
+  [
+    createBlockNoteExtension({
+      key: "quote-block-shortcuts",


Let's think about a higher level (not transaction) specific API for the keyboard shortcuts. I see I commented this earlier, but let's discuss

I don't know that there is one. Keyboard shortcuts can do pretty much anything. There could be an easier API for doing things like adding a new block of a certain type or updating a block to a certain type. But I'd argue that is useful outside of keyboard shortcuts so it is better to leave them be top-level things (e.g. editor.addBlock({ type: string; props: Record<string, unknown> }))

If you have something specific you'd like to see, feel free to mention it!

YousefED · 2025-09-01T12:08:30Z

packages/core/src/blocks/Quote/block.ts

+        dom: quote,
+        contentDOM: quote,
+      };
+    },


I'd be interested to see what we can come up with if we think about this API further. Things I think are within reach:

decouple this further from block specs / schema

make it easy to change / disable shortcuts / input rules

Related to this comment: https://blocknotejs.slack.com/archives/C01G3C47338/p1756719142481359?thread_ts=1756716444.502609&cid=C01G3C47338

maybe brainstorm together this week at office? good to research how the (de)coupling (between editor behavior vs schemas vs rendering) works in other editors?

YousefED · 2025-09-01T12:11:59Z

packages/core/src/blocks/ListItem/NumberedListItem/IndexingPlugin.ts

+          Decoration.node(pos + 1, pos + node.nodeSize - 1, {
+            "data-index": index.toString(),
+            // TODO figure out start? is this needed?
+            // "data-start": hasStart ? index.toString() : undefined,


TODO (just commenting here to make sure we don't miss it)

YousefED · 2025-09-01T12:17:57Z

packages/core/src/blocks/BlockNoteSchema.ts

+  defaultStyleSpecs,
+} from "./defaultBlocks.js";
+
+export class BlockNoteSchema<


why do we have both BlockNoteSchema and CustomBlockNoteSchema?

BlockNoteSchema is a thin wrapper over CustomBlockNoteSchema. CustomBlockNoteSchema is the actual implementation & does not set any of the default blocks & requires the schema to be fully specified.

BlockNoteSchema will pre-load all of the default blocks too, this separation is to allow BlockNoteSchema to be tree-shaken off if it is not needed by someone. They can just use CustomBlockNoteSchema and provide everything they will actually include in their editor.

YousefED · 2025-09-01T12:46:15Z

packages/core/src/schema/propTypes.ts

@@ -9,6 +9,7 @@ export type PropSpec<PType extends boolean | number | string> =
  | {
      // We infer the type of the prop from the default value
      default: PType;
+      type?: "string" | "number" | "boolean";


sure this is needed? previously this was inferred from the default I think

packages/core/src/schema/blocks/createSpec.ts

YousefED · 2025-09-01T12:56:08Z

packages/react/src/components/Comments/schema.ts

-  ),
-  // disable default props on paragraph (such as textalignment and colors)
-  {},
-);

 // remove textColor, backgroundColor from styleSpecs
 const { textColor, backgroundColor, ...styleSpecs } = defaultStyleSpecs;

 // the schema to use for comments
 export const schema = BlockNoteSchema.create({


YousefED · 2025-09-01T13:07:51Z

packages/react/src/schema/ReactBlockSpec.tsx

+                className: "bn-react-node-view-renderer",
+              },
+            )(this.props!) as ReturnType<BlockImplementation["render"]>;
+          } else {


when does this get called? wouldn't this be covered by toExternalHTML or am I missing a scenario?

packages/react/src/schema/ReactBlockSpec.tsx

YousefED · 2025-09-01T13:25:39Z

Just noticed this example is broken: http://localhost:5173/custom-schema/react-custom-blocks (try changing alert type). Can you or @matthewlipski also add a test for this?
Let's double check the React block and React ic / styles for rendering performance. In my experience this is easy to break when changing the addNodeView related code

… default-blocks

nperez0111 added 3 commits July 28, 2025 12:59

feat: wip

fcdbf18

feat: topological sorting, input rules and keyboard shortcuts

e1bb45e

feat: move code block over too

6b10846

feat: getContent parsing for custom blocks

92952e7

vercel bot had a problem deploying to Preview – blocknote August 1, 2025 10:22 Failure

vercel bot had a problem deploying to Preview – blocknote-website August 1, 2025 10:23 Failure

nperez0111 added 3 commits August 1, 2025 15:28

fix: render toggle lists

6d85ef5

fix: toggle headings

ec77940

refactor: custom schema, which depends on no blocks

809ea0a

vercel bot had a problem deploying to Preview – blocknote August 1, 2025 13:39 Failure

vercel bot had a problem deploying to Preview – blocknote-website August 1, 2025 13:40 Failure

matthewlipski reviewed Aug 1, 2025

View reviewed changes

YousefED reviewed Aug 4, 2025

View reviewed changes

nperez0111 added 2 commits August 4, 2025 17:59

refactor: trying to fit it in

b46fcc6

fix: get tables working

5751974

vercel bot had a problem deploying to Preview – blocknote August 4, 2025 16:12 Failure

vercel bot had a problem deploying to Preview – blocknote-website August 4, 2025 16:13 Failure

matthewlipski and others added 7 commits August 5, 2025 22:43

Made type guards more generic

c51767a

Updated type guard definitions

97295ce

Small fix

1ff7474

feat: getting somewhere

9918510

Merge branch 'default-blocks-type-guards' into default-blocks

1e0e059

Removed checkDefaultInlineContentTypeInSchema

fc9e452

Small fixes

a0fc6e2

vercel bot had a problem deploying to Preview – blocknote August 7, 2025 12:16 Failure

vercel bot had a problem deploying to Preview – blocknote-website August 7, 2025 12:16 Failure

fix: better parsing for headings

cda8eb6

vercel bot had a problem deploying to Preview – blocknote August 7, 2025 14:31 Failure

vercel bot had a problem deploying to Preview – blocknote-website August 7, 2025 14:32 Failure

Updated unit test snaps

5e3cad6

YousefED reviewed Sep 1, 2025

View reviewed changes

vercel bot had a problem deploying to Preview – blocknote-website September 1, 2025 08:46 Failure

vercel bot had a problem deploying to Preview – blocknote September 1, 2025 08:47 Failure

YousefED reviewed Sep 1, 2025

View reviewed changes

packages/xl-multi-column/src/blocks/schema.ts Show resolved Hide resolved

chore: simpler as const

069f88f

YousefED reviewed Sep 1, 2025

View reviewed changes

nperez0111 and others added 2 commits September 1, 2025 11:15

fix: rm heading & code-block opts

f4a0316

Removed codeBlock and heading editor options & updated custom cod…

26b9b1c

…e block examples

vercel bot had a problem deploying to Preview – blocknote September 1, 2025 09:18 Failure

vercel bot had a problem deploying to Preview – blocknote-website September 1, 2025 09:19 Failure

matthewlipski added 2 commits September 1, 2025 11:22

Merge branch 'default-blocks-deprecate-options' into default-blocks

356aedc

Update examples

80963f4

vercel bot had a problem deploying to Preview – blocknote September 1, 2025 09:24 Failure

vercel bot had a problem deploying to Preview – blocknote-website September 1, 2025 09:25 Failure

Updated code block docs & package export name

8ef6188

YousefED reviewed Sep 1, 2025

View reviewed changes

vercel bot had a problem deploying to Preview – blocknote-website September 1, 2025 09:50 Failure

vercel bot had a problem deploying to Preview – blocknote September 1, 2025 09:51 Failure

YousefED reviewed Sep 1, 2025

View reviewed changes

packages/core/src/schema/blocks/types.ts Show resolved Hide resolved

YousefED reviewed Sep 1, 2025

View reviewed changes

packages/core/src/blocks/PageBreak/getPageBreakSlashMenuItems.ts Show resolved Hide resolved

YousefED reviewed Sep 1, 2025

View reviewed changes

chore: update comments

6b7bad8

vercel bot had a problem deploying to Preview – blocknote September 1, 2025 13:36 Failure

vercel bot had a problem deploying to Preview – blocknote-website September 1, 2025 13:37 Failure

matthewlipski added 2 commits September 1, 2025 18:04

Fixed React custom block interactivity not working & added tests

5dc2544

Merge branch 'default-blocks' of github.com:TypeCellOS/BlockNote into…

87e57e3

… default-blocks

vercel bot had a problem deploying to Preview – blocknote September 1, 2025 16:06 Failure

vercel bot had a problem deploying to Preview – blocknote-website September 1, 2025 16:07 Failure

Uh oh!

refactor: move all blocks to use the custom blocks API #1904

Are you sure you want to change the base?

refactor: move all blocks to use the custom blocks API #1904

Conversation

nperez0111 commented Aug 1, 2025 • edited by matthewlipski Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

TODO:

Uh oh!

vercel bot commented Aug 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

matthewlipski left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

YousefED left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nperez0111 Sep 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

YousefED Sep 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

YousefED Sep 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

nperez0111 commented Aug 1, 2025 •

edited by matthewlipski

Loading

vercel bot commented Aug 1, 2025 •

edited

Loading

nperez0111 Sep 1, 2025 •

edited

Loading

YousefED Sep 1, 2025 •

edited

Loading

YousefED Sep 1, 2025 •

edited

Loading