Custom blocks cannot be nested in the editor

Describe the bug
Some blocks cannot be nested, including all custom blocks. For instance, editing a custom block in the editor and inserting a heading will make the heading appear below the custom block, instead of inside it.

Inserting a custom block inside another will result in the same behavior.

There's already another issue on that matter, but a reproduction example was apparently missing, so I'll provide one here.

To Reproduce
Minimal reproduction sandbox: https://stackblitz.com/edit/github-df1nzmdk
In the editor, type /wrapper to insert the custom demo element, then inside it type /wrapper again (or some other 'big' blocks like headings). Insert of the element being inserted inside the first wrapper, it is created below it.

Misc

Node version: v22.14.0
Package manager: 10.5.0
Browser: Firefox 136

This is the problem I'm currently facing as well.

I'm building an Accordion (toggle list) custom block, and I want to be able to have a nested Accordion inside of the content, but it seem impossible to do that within the current version.

@ClementEXWiki

At this point, BlockNote does not support nested custom blocks indeed. If we're adding an API for this, I think we need to carefully design it to:

keep the regular API surface simple (i.e.: not add an enormous amount of complexity, specifically for this feature)
ideally, make it work with the strongly-typed schema that BlockNote supports

More importantly; we need to make sure we can implement this without introducing all kinds of UX quirks that would need to be handled manually per type of nested blocks users want to add. e.g.: do different types of nested blocks have different requirements in terms of cursor / key handling?

Let's use this thread to collect different kind of nested blocks that people want to add so we can identify if (and which) an API for this makes sense:

Toggle list
Blocks within Callouts / alerts (Help needed: Nested Custom Blocks (IF/LOOP) in BlockNote #1368 video)
"IF" / "Loop" logical blocks (Help needed: Nested Custom Blocks (IF/LOOP) in BlockNote #1368)
blocks inside of tables: Images in table cells #1514 Can't add checkbox in table #1814
marks in image caption: Enable marks inside image caption #551
... (@ClementEXWiki what are you looking to build with this?)

I'm trying to replace the current editor we have at XWiki (CKEditor 4) with a more modern approach. We are rebuilding the editor and a lot of things that revolve around it, it's a pretty massive project.

One of the features we need to support is macros. Basically these are custom blocks that are rendered either cilent-side or server-side, and most of them can be nested.

One example of such macros would be the alert example you give in the docs. You have a banner with a yellow / blue / red background and some icon, and inside that you put some content. But you should be able to put some headings inside, some blockquotes, some code blocks, and so on.

We have hundreds of macros and are writing new ones very frequently, and they need to support nested blocks.

We could use some hacks to make nested blocks work but they would be just that - hacks. Having actual first-party support in BlockNote would be immensely better. Now I don't know how hard it would be to implement, maybe it's very difficult, so I'm just exposing the context of the feature request.

For the API design part, I'm not sure there are tons of things to change - the current types already support block nesting, e.g.:

const editor = useCreateBlockNote({
  initialContent: [
    {
      type: "alert",
      children: [{ type: "alert" }],
    },
  ],
});

Works just fine, and we have correct typing (so we inner alert type is autocompleted in the IDE).

I think support for nested blocks should be as simple as possible: their content can be anything that you would write anywhere in the editor. So custom blocks would either have no content, inline content, or "full nested" content - which includes headings, blockquotes, etc.

What do you think?

I see that some default modules support nesting, like bulletListItem, so what is the difficulty of the api of custom nested blocks?

@YousefED

@YousefED Here also has my requirement for

Stepper:
Tabs:

@ClementEXWiki

Also requesting this feature. What have others landed on?

What hacks are you talking about @ClementEXWiki ?

BlockNote supports custom blocks and nested blocks but not nested custom blocks, which I found surprising!

What hacks are you talking about @ClementEXWiki ?

One way of doing this would be to put a full BlockNote editor DOM inside each custom block. This would be a disaster in terms of performance and be a very ugly hack, but it would work.

Yes, I'm also looking for this functionality. Arbitrary nesting of arbitrary blocks would be ideal.

Just chiming in to say that this would be a highly desirable feature for us too. Even just nesting images etc in the tables would be a great step forward. We are developing a django app to use BN and I can already see our users asking for table nesting.

I also really want this! Trying to implement toggle lists and its a pain.

I was able to use the CSS has: selector to style parent containers to create the effect I am going for but it seems like a hack and there are styling bugs related to the + :: buttons for nested items that I have only partially dealt with.

This feature would be SO valuable, along with the ability to nest blocks inside tables. I hope this gets implemented soon ! 🙏

@YousefED

@YousefED Is it currently possible to nest blocks inside a Quote block, like in Notion ? If not, could you add it to the list please

I've also got a use case that's running into restrictions here. We've currently got a structured profile page made up of a bunch of sections, each containing:

an image to the left (or right), and
a heading, description, and body text to the right (or left).

We're trying to replace this structured profile page with a WYSIWYG editor and renderer based on BlockNote. Ideally we'd represent each section using a block that stores and renders the image, and then users could nest headings/descriptions/text/video embeds/tables/lists/etc. within that block.

We were confused by the foundations section of the docs. The docs say that a block can have child blocks nested within it. There appears to be no way to do this without touching ProseMirror. There are also no guides or examples of how to do this other than the columns package, which nobody's allowed to use as a reference because of license contamination.

We were confused by the foundations section of the docs. The docs say that a block can have child blocks nested within it. There appears to be no way to do this without touching ProseMirror. There are also no guides or examples of how to do this other than the columns package, which nobody's allowed to use as a reference because of license contamination.

Blocks can actually be nested ; just not custom blocks. But you can absolutely have a list (which is a block) inside a paragraph for instance.

Blocks can actually be nested ; just not custom blocks. But you can absolutely have a list (which is a block) inside a paragraph for instance.

Yeah, sorry, that's what I meant: I can't have blocks nested within my custom blocks. (Or at least there's no easy, documented way to do it - I have the feeling that the columns blocks do it, but I can't read the code for those because of license reasons.)

I read the docs and came away with the impression that a user would be able to implement a tree structure using blocks they had written, which sadly isn't the case. Ideally the docs would mention that only built-in blocks get to nest other blocks within themselves.

We would like to propose some improvements regarding table functionality, which we believe will significantly enhance the readability and versatility of documents created by users.

Currently, when users create documents using tables, there is limited flexibility in styling and content options. Implementing the following features would allow users to compose tables with diverse styles and information, leading to much higher readability.

1. Table Cell Styling Enhancements:

Cell Vertical Alignment:
Implement options for Top, Middle, and Bottom vertical alignment within cells. This will allow users to better manage the visual presentation of content within cells of varying sizes.

Cell Borders:
Provide comprehensive border styling options for tables and individual cells. This will enable users to emphasize or group information effectively within the table structure.
Border Styles: Solid, Dashed, Double
Border Thickness: 0px to 10px (with appropriate increments)
Border Color: Option to match the text color, or a dedicated color picker.

2. Enhanced Cell Content Options (Multiple Block Support):

Multiple Block Creation within a Cell:

Allow users to insert and arrange multiple content blocks within a single table cell.
Diverse Block Types:

Support the insertion of various block types within table cells, including:

Numbered List
Bullet List
Check List
Code Block
Image
Video
Audio
File

We believe these enhancements will greatly improve the user experience and the quality of documents created using your platform.

Thank you for your consideration.

I just want the table to be nested with images, headings, etc. Thk

This would be hugely valuable, was a little surprised that you could not nest custom blocks. 🥲
So i'll have to work around somehow for now.

Navigation Menu

Repository navigation

Custom blocks cannot be nested in the editor #1540

2 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Custom blocks cannot be nested in the editor #1540

Description

Activity

leTranTienPhat commented on Mar 19, 2025

YousefED commented on Mar 19, 2025

ClementEXWiki commented on Mar 19, 2025

sailxjx commented on Mar 24, 2025

FatefulNur commented on Apr 7, 2025

AgainstLightning commented on May 16, 2025

ClementEXWiki commented on May 16, 2025

andrewluetgers commented on May 29, 2025

rsevs3 commented on Jun 5, 2025

jedmund commented on Jun 6, 2025

andrewluetgers commented on Jun 6, 2025

2 remaining items

CodingSoot commented on Jul 18, 2025

CodingSoot commented on Jul 21, 2025

stretchkennedy commented on Jan 5, 2026

ClementEXWiki commented on Jan 5, 2026

stretchkennedy commented on Jan 5, 2026

seyoung77 commented on Jan 8, 2026

luBenWei-55kai commented on Jan 9, 2026

kyletully commented on Jan 27, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions