feat: Toggle blocks #1707

matthewlipski · 2025-05-21T21:38:00Z

Toggle wrapper element/component

This PR adds a new component, ToggleWrapper, as well as a vanilla HTML element implementation of it, createToggleWrapper. These can be used to wrap existing blocks, or create new ones and allow the user to toggle showing/hiding their children.

The toggle wrapper renders a button to the left of the block to show/hide the children. Additionally, if children are shown but none exist, a button is rendered to prompt the user to add a block. Because the toggled state is only in the view, toggling the visibility of children only happens client-side when using collaboration.

A toggledState object can also be passed to the toggle wrapper, which includes a get and set function to be able to preserve the state on re-render and reload. By default, this is done using local storage.

Schema changes

This PR also adds toggle headings and toggle list items to the default editor schema.

The toggle headings are implemented by adding an isToggleable prop, and rendering the block in a toggle wrapper when this is set to true.

The toggle list item is a new, separate block, which always renders a paragraph in a toggle wrapper. Like the other list items though, hitting Enter in one creates a new block of the same type, which is why I made it a separate block rather than adding isToggleable to the existing paragraph or list item blocks. Additionally, the block is exported differently to formats like docx, as the content gets prepended with a ">".

TODO

Currently some xl-ai tests are failing, and these have been temporarily disabled.

Closes #196
Closes #549
Closes #910

vercel · 2025-05-21T21:38:04Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
blocknote	✅ Ready (Inspect)	Visit Preview	Jun 20, 2025 9:53am
blocknote-website	❌ Failed (Inspect)		Jun 20, 2025 9:53am

pkg-pr-new · 2025-05-21T21:44:40Z

Open in StackBlitz

@blocknote/ariakit

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/ariakit@1707

@blocknote/code-block

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/code-block@1707

@blocknote/core

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/core@1707

@blocknote/mantine

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/mantine@1707

@blocknote/react

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/react@1707

@blocknote/server-util

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/server-util@1707

@blocknote/shadcn

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/shadcn@1707

@blocknote/xl-ai

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-ai@1707

@blocknote/xl-docx-exporter

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-docx-exporter@1707

@blocknote/xl-multi-column

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-multi-column@1707

@blocknote/xl-odt-exporter

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-odt-exporter@1707

@blocknote/xl-pdf-exporter

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-pdf-exporter@1707

commit: 5435942

nperez0111

What I'm more interested in seeing here is how we can add this to existing block types (such as headings with a prop) rather than as a separate element like this implements.

packages/core/src/blocks/ToggleHeadingBlockContent/ToggleHeadingBlockContent.ts

…heading

nperez0111

Does isToggleable have to show up on every element now? Can it not just be assumed false if undefined? Or, do we always render "default values"?

packages/core/src/blocks/HeadingBlockContent/HeadingBlockContent.ts

packages/core/src/blocks/ToggleWrapper/createToggleWrapper.ts

packages/core/src/editor/Block.css

nperez0111 · 2025-06-16T15:20:04Z

packages/core/src/extensions/SuggestionMenu/getDefaultSlashMenuItems.ts

+      {
+        onItemClick: () => {
+          insertOrUpdateBlock(editor, {
+            type: "heading",
+            props: { level: 1, isToggleable: true },
+          });
+        },
+        key: "toggle_heading",
+        ...editor.dictionary.slash_menu.toggle_heading,
+      },
+      {


Is there a way to disable toggleable headings but not headings?

I think so, you could just do getDefaultSlashMenuItems(...).filter((item) => !item.key.startsWith("toggle_heading")) right? So pretty much the same way you'd filter out any other items from the menu. Or do you mean in the schema itself?

I meant from the schema

Ah, in that case not really but I think it's ok for now, seems like something that will get fixed either way when converting default blocks to use the custom blocks API.

packages/react/src/blocks/ToggleWrapper/ToggleWrapper.tsx

YousefED

Awesome, almost there I think!

empty toggle list should have a placeholder "Toggle" (same as Notion)

~~I don't think this works?~~

Others:

let's make the font color of the "add button" placeholder more placeholder-like (gray?)
Is it easy to remove the vertical lines for toggled blocks? imo this still looks a bit weird

One architectural question:

I realize we're currently following notion in this design, but let's make sure having an is_toggleable prop on a heading makes more sense than having a separate ToggleHeading block. What are the pros / cons? (cc @nperez0111 )

YousefED · 2025-06-18T11:38:37Z

packages/core/src/blocks/ToggleWrapper/createToggleWrapper.ts

+
+export const defaultToggledState: ToggledState = {
+  set: (block, isToggled: boolean) =>
+    window.localStorage.setItem(


should we move this logic (whether to store to local storage) to be configurable on the editor? Or want to keep it as part of the block spec (and thus the schema)?

cc @nperez0111

imo, for now, part of the block spec (lowest-level possible).

In the future, this would be a "bundle" that you can configure independently

YousefED · 2025-06-18T11:41:16Z

...ore/src/blocks/ListItemBlockContent/ToggleListItemBlockContent/ToggleListItemBlockContent.ts

+  ...defaultProps,
+} satisfies PropSchema;
+
+const ToggleListItemBlockContent = createStronglyTypedTiptapNode({


Food for thought; when streamlining built-in blocks, I'm curious if we can come up with a light-weight way to make this more readable (React / jsx like), without pulling in all of react. And thus, get rid of the duplicate (vanilla + react) implementation

cc @nperez0111

Yes, I have ideas for this. Basically use jsx for actual document.createElement calls, without all of React. In my ideal, you wouldn't even need React.

YousefED · 2025-06-18T12:41:50Z

packages/core/src/editor/Block.css

@@ -204,9 +206,11 @@ NESTED BLOCKS
 }

 /* Unordered */
-.bn-block-content[data-content-type="bulletListItem"] {
+.bn-block-content[data-content-type="bulletListItem"]::before {


can you explain why this changed? why the before element that wasn't here earlier?

Ah I forgot to mention this in the PR description - I adjusted offsets for list items, indented blocks, and the "add block" button of the toggle blocks to make them all the same. So all of these are now vertically in-line now, and these styles are a part of that.

nperez0111 · 2025-06-18T12:52:47Z

I realize we're currently following notion in this design, but let's make sure having an is_toggleable prop on a heading makes more sense than having a separate ToggleHeading block. What are the pros / cons? (cc @nperez0111 )

My argument for this was that let's say you were generating the table of contents for a page, would you consider a heading that happens to be toggle-able, not a heading? By making it a different block, you change the semantics of what it is, whereas toggling is purely a visual thing (much like setting a background color wouldn't change the type of block it is)

YousefED · 2025-06-18T14:44:25Z

I realize we're currently following notion in this design, but let's make sure having an is_toggleable prop on a heading makes more sense than having a separate ToggleHeading block. What are the pros / cons? (cc @nperez0111 )

My argument for this was that let's say you were generating the table of contents for a page, would you consider a heading that happens to be toggle-able, not a heading? By making it a different block, you change the semantics of what it is, whereas toggling is purely a visual thing (much like setting a background color wouldn't change the type of block it is)

Good point. Going to challenge a bit more to make sure we're confident (I still don't think I have a preference, or maybe start to prefer the current implementation):

Following your reasoning, does it still make sense the toggle list items are different from regular lists?
Having separate blocks would solve things like this, right? feat: Toggle blocks #1707 (comment)

nperez0111 · 2025-06-18T14:59:32Z

Good point. Going to challenge a bit more to make sure we're confident (I still don't think I have a preference, or maybe start to prefer the current implementation):
* Following your reasoning, does it still make sense the toggle list items are different from regular lists?

Good point, I'd argue that these should actually be named toggleBlocks rather than a list item, and they roughly correspond to the <details> element in HTML: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/details.

UI-wise, the naming could be different for understanding maybe, but, I think, they are functionally equivalent. List does sort of convey that hitting enter, you'd get more of them.

List items are actually the perfect demonstration of what I mean here about semantics, it is always an li but what it is wrapped (e.g. <ul>) in that determines it's display.

* Having separate blocks would solve things like this, right? [feat: Toggle blocks #1707 (comment)](https://github.com/TypeCellOS/BlockNote/pull/1707#discussion_r2150279943)

I think what would solve this is the ability to easily customize the schema. In this case, I'd want an option to remove isToggable from the prop schema, and if that prop schema is completely missing, we could hide the slash menu items as not being applicable.

matthewlipski · 2025-06-18T16:36:20Z

To follow up with the naming convention for toggleListItem - worth mentioning that this is how Notion represents them too.

Also r.e. the <details> element, I agree this would be nice to use though I'm not 100% sure it fits within our HTML structure. Basically the hidden content, i.e. the blockGroup, should be inside it below the <summary> element, which we can't really do since it's outside of the blockContent element.

YousefED · 2025-06-19T06:48:06Z

packages/core/src/i18n/locales/nl.ts

@@ -157,7 +157,7 @@ export const nl: Dictionary = {
  placeholders: {
    default: "Voer tekst in of type '/' voor commando's",
    heading: "Kop",
-    toggleList: "Schakelaar",
+    toggleListItem: "Schakelaar",


This word means "switch" (as in, "light switch" / "light toggle").

Can we give your AI some extra context to improve the translations?

Hmm, I'm just using Copilot built into VSCode so it should at least have the context of the english translation file, any way I can add to this?

I think you can @ mention specific files in the chat? It also helps to just chat explanation of what the toggle is (i.e.: a block that expands in a document editor)

YousefED · 2025-06-19T06:48:47Z

List does sort of convey that hitting enter, you'd get more of them.

@nperez0111 that's also the case.

I'm starting to think that the current naming is ok - unless anyone feels otherwise after the above discussion

nperez0111 · 2025-06-19T07:48:18Z

I think the current naming is okay if it keeps the newline behavior. If someone wants to disable that, then it should be called a toggle block.

But, obviously no way for us to enforce it.

Agreed, naming is fine here.

nperez0111 · 2025-06-20T11:13:54Z

Thought about it, & decided it was fine like this:

If you want there to be both toggle & not toggable headings, that is the default
If you want only not toggable headings, we could disable the view layer from wrapping the heading with the creatToggleWrapper
If you want only toggable headings, you would similarly just enforce that the view layer to always be wrapped in a toggleable

matthewlipski added 3 commits May 21, 2025 18:37

Added toggle heading

d893c6a

Changed collapsible heading to toggle and added react implementation

d77eca5

Removed duplicate code

ec26e4d

Small changes

00fbdae

vercel bot deployed to Preview – blocknote-website May 21, 2025 22:05 View deployment

vercel bot deployed to Preview – blocknote May 21, 2025 22:08 View deployment

nperez0111 reviewed Jun 6, 2025

View reviewed changes

matthewlipski added 2 commits June 10, 2025 15:54

Extracted toggle to separate component

9d148ae

Added missing export

7a7a2db

vercel bot deployed to Preview – blocknote-website June 10, 2025 14:06 View deployment

vercel bot deployed to Preview – blocknote June 10, 2025 14:09 View deployment

Added vanilla toggle heading block

a484779

vercel bot had a problem deploying to Preview – blocknote June 10, 2025 20:27 Failure

vercel bot had a problem deploying to Preview – blocknote-website June 10, 2025 20:28 Failure

matthewlipski added 2 commits June 10, 2025 22:54

Added translations

7ce587d

Typing fix

cb159d6

vercel bot deployed to Preview – blocknote June 10, 2025 20:57 View deployment

vercel bot deployed to Preview – blocknote-website June 10, 2025 21:04 View deployment

Made heading custom block to extend for toggle heading

d7a6d7d

vercel bot had a problem deploying to Preview – blocknote June 11, 2025 08:44 Failure

vercel bot had a problem deploying to Preview – blocknote-website June 11, 2025 08:45 Failure

Small fix

a3a88f9

vercel bot had a problem deploying to Preview – blocknote June 11, 2025 08:50 Failure

vercel bot had a problem deploying to Preview – blocknote-website June 11, 2025 08:51 Failure

nperez0111 reviewed Jun 11, 2025

View reviewed changes

packages/core/src/blocks/ToggleHeadingBlockContent/ToggleHeadingBlockContent.ts Outdated Show resolved Hide resolved

Removed toggle heading block and added isTogglable prop to regular …

2c12f1b

…heading

vercel bot deployed to Preview – blocknote June 11, 2025 09:38 View deployment

vercel bot deployed to Preview – blocknote-website June 11, 2025 09:46 View deployment

Updated PW snaps

09608a5

vercel bot deployed to Preview – blocknote-website June 16, 2025 14:41 View deployment

matthewlipski requested review from nperez0111 and YousefED June 16, 2025 14:42

vercel bot deployed to Preview – blocknote June 16, 2025 14:44 View deployment

nperez0111 requested changes Jun 16, 2025

View reviewed changes

Implemented PR feedback

33912b8

vercel bot deployed to Preview – blocknote June 16, 2025 21:10 View deployment

vercel bot deployed to Preview – blocknote-website June 16, 2025 21:18 View deployment

Updated PW snaps

df3c678

vercel bot deployed to Preview – blocknote June 17, 2025 08:44 View deployment

vercel bot deployed to Preview – blocknote-website June 17, 2025 08:51 View deployment

YousefED reviewed Jun 18, 2025

View reviewed changes

Implemented PR feedback

6f31924

vercel bot deployed to Preview – blocknote June 18, 2025 17:00 View deployment

vercel bot had a problem deploying to Preview – blocknote-website June 18, 2025 17:09 Failure

YousefED reviewed Jun 19, 2025

View reviewed changes

nperez0111 added 2 commits June 20, 2025 11:17

chore: update translations

c8df257

chore: update translations

5435942

vercel bot deployed to Preview – blocknote June 20, 2025 09:33 View deployment

vercel bot had a problem deploying to Preview – blocknote-website June 20, 2025 09:40 Failure

nperez0111 merged commit 788c5b8 into main Jun 20, 2025
7 of 8 checks passed

nperez0111 deleted the toggle-blocks branch June 20, 2025 11:11

Uh oh!

feat: Toggle blocks #1707

feat: Toggle blocks #1707

Uh oh!

Conversation

matthewlipski commented May 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Toggle wrapper element/component

Schema changes

TODO

Uh oh!

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

Uh oh!

Uh oh!

pkg-pr-new bot commented May 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nperez0111 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nperez0111 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

YousefED left a comment • edited by matthewlipski 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!

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!

nperez0111 commented Jun 18, 2025

Uh oh!

YousefED commented Jun 18, 2025

Uh oh!

nperez0111 commented Jun 18, 2025

Uh oh!

matthewlipski commented Jun 18, 2025

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 commented Jun 19, 2025

Uh oh!

nperez0111 commented Jun 19, 2025

Uh oh!

Uh oh!

nperez0111 commented Jun 20, 2025

Uh oh!

matthewlipski commented May 21, 2025 •

edited

Loading

vercel bot commented May 21, 2025 •

edited

Loading

pkg-pr-new bot commented May 21, 2025 •

edited

Loading

YousefED left a comment •

edited by matthewlipski

Loading