TypeCellOS · YousefED · Sep 29, 2026 · Sep 29, 2026 · Sep 29, 2026
diff --git a/examples/06-custom-schema/14-tabs-block/.bnexample.json b/examples/06-custom-schema/14-tabs-block/.bnexample.json
@@ -0,0 +1,12 @@
+{
+  "playground": true,
+  "docs": false,
+  "author": "claude",
+  "tags": ["Intermediate", "Blocks", "Custom Schemas"],
+  "dependencies": {
+    "react-icons": "^5.5.0",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2"
+  }
+}
diff --git a/examples/06-custom-schema/14-tabs-block/README.md b/examples/06-custom-schema/14-tabs-block/README.md
@@ -0,0 +1,46 @@
+# Tabs Block
+
+A tab set built on the container block API. `tabs` is a container whose
+`children` are restricted to `tab` panels, and `tab` is a `placeable:
+"namedOnly"` container, so a panel can only ever exist inside a tab set —
+the schema enforces both.
+
+Each panel holds any block. A panel's label is document content and lives in
+its props. Which panel is open is not: it belongs to each reader, so it is kept
+outside the document, in `localStorage` keyed by the tab set's id. Switching
+tabs is therefore not an undo step and is not sent to collaborators.
+
+**Try it out:** Click a tab to open it, click the open tab for its menu, and
+drag a tab to reorder it.
+
+## What a tab set needs beyond the container API
+
+**Revealing the panel the caret lands in.** A hidden panel is still part of the
+document, so the editor will move content into it: Backspace at the start of
+the block after a tab set pulls that block into the last panel, which may not
+be the open one. `useRevealCaretPanel` opens whichever panel the caret ends up
+in, using `editor.onSelectionChange`, so every route in (Backspace, Delete,
+arrow keys, drag and drop, paste) is covered at once.
+
+**Moving the caret when a tab is clicked.** An explicit switch takes the caret
+with it when the caret was inside the set. Otherwise the reveal above would
+immediately reopen the panel it was left in.
+
+**A menu instead of buttons.** Clicking the open tab opens a menu to rename,
+move or delete it. It is built from `useComponentsContext()`, so it matches
+whichever UI library the editor uses.
+
+**Drag to reorder.** Tabs are sortable with dnd-kit. A tab keeps its block id
+when it moves, so the reader's open tab follows it.
+
+## Known limitation
+
+Emptying a panel removes it, label included, because the container repair
+treats a panel holding only an empty paragraph as empty. Removing the last
+non-empty panel can therefore dissolve the whole tab set. The container API
+has no way for a block to opt out of this yet.
+
+**Relevant Docs:**
+
+- [Container Blocks](/docs/features/custom-schemas/container-blocks)
+- [Custom Blocks](/docs/features/custom-schemas/custom-blocks)
diff --git a/examples/06-custom-schema/14-tabs-block/index.html b/examples/06-custom-schema/14-tabs-block/index.html
@@ -0,0 +1,14 @@
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Tabs Block</title>
+    <script>
+      <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>
diff --git a/examples/06-custom-schema/14-tabs-block/main.tsx b/examples/06-custom-schema/14-tabs-block/main.tsx
@@ -0,0 +1,11 @@
+// AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY
+import React from "react";
+import { createRoot } from "react-dom/client";
+import App from "./src/App.jsx";
+
+const root = createRoot(document.getElementById("root")!);
+root.render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);
diff --git a/examples/06-custom-schema/14-tabs-block/package.json b/examples/06-custom-schema/14-tabs-block/package.json
@@ -0,0 +1,34 @@
+{
+  "name": "@blocknote/example-custom-schema-tabs-block",
+  "description": "AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY",
+  "type": "module",
+  "private": true,
+  "version": "0.12.4",
+  "scripts": {
+    "start": "vite",
+    "dev": "vite",
+    "build:prod": "tsc && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@blocknote/ariakit": "latest",
+    "@blocknote/core": "latest",
+    "@blocknote/mantine": "latest",
+    "@blocknote/react": "latest",
+    "@blocknote/shadcn": "latest",
+    "@mantine/core": "^9.0.2",
+    "@mantine/hooks": "^9.0.2",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "react-icons": "^5.5.0",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.3",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "vite": "^8.0.0"
+  }
+}
diff --git a/examples/06-custom-schema/14-tabs-block/src/App.tsx b/examples/06-custom-schema/14-tabs-block/src/App.tsx
@@ -0,0 +1,109 @@
+import { BlockNoteSchema } from "@blocknote/core";
+import {
+  filterSuggestionItems,
+  insertOrUpdateBlockForSlashMenu,
+} from "@blocknote/core/extensions";
+import "@blocknote/core/fonts/inter.css";
+import { BlockNoteView } from "@blocknote/mantine";
+import "@blocknote/mantine/style.css";
+import {
+  SuggestionMenuController,
+  getDefaultReactSlashMenuItems,
+  useCreateBlockNote,
+} from "@blocknote/react";
+import { RiLayoutTopLine } from "react-icons/ri";
+
+import { createTab, createTabs } from "./Tabs";
+import "./styles.css";
+
+const schema = BlockNoteSchema.create().extend({
+  blockSpecs: {
+    tabs: createTabs(),
+    tab: createTab(),
+  },
+});
+
+// A tab set is only useful with its panels, so the slash menu inserts both.
+function insertTabs(editor: typeof schema.BlockNoteEditor) {
+  return {
+    title: "Tabs",
+    subtext: "A tab strip with one panel per tab",
+    onItemClick: () =>
+      insertOrUpdateBlockForSlashMenu(editor, {
+        type: "tabs",
+        children: [
+          {
+            type: "tab",
+            props: { label: "First" },
+            children: [{ type: "paragraph", content: "First panel" }],
+          },
+          {
+            type: "tab",
+            props: { label: "Second" },
+            children: [{ type: "paragraph", content: "Second panel" }],
+          },
+        ],
+      } as any),
+    aliases: ["tabs", "tab"],
+    group: "Basic blocks",
+    icon: <RiLayoutTopLine />,
+  };
+}
+
+export default function App() {
+  const editor = useCreateBlockNote({
+    schema,
+    initialContent: [
+      {
+        type: "paragraph",
+        content: "Tabs built on the container API. Each panel holds any block.",
+      },
+      {
+        // A persistent ID so the open tab is remembered across reloads: the
+        // choice is stored per tab-set id, and a fresh document would
+        // otherwise get a fresh one.
+        id: "tabs-demo",
+        type: "tabs",
+        children: [
+          {
+            // Persistent IDs alongside the set's, so the remembered choice
+            // still names a panel after a reload.
+            id: "tab-install",
+            type: "tab",
+            props: { label: "Install" },
+            children: [
+              { type: "heading", props: { level: 3 }, content: "Install" },
+              { type: "paragraph", content: "Run the installer, then reboot." },
+              { type: "bulletListItem", content: "Any block works in here" },
+            ],
+          },
+          {
+            id: "tab-configure",
+            type: "tab",
+            props: { label: "Configure" },
+            children: [
+              { type: "heading", props: { level: 3 }, content: "Configure" },
+              { type: "paragraph", content: "Edit the config file." },
+            ],
+          },
+        ],
+      } as any,
+      { type: "paragraph", content: "Press '/' to insert another tab set." },
+      { type: "paragraph" },
+    ],
+  });
+
+  return (
+    <BlockNoteView editor={editor} slashMenu={false}>
+      <SuggestionMenuController
+        triggerCharacter={"/"}
+        getItems={async (query) =>
+          filterSuggestionItems(
+            [...getDefaultReactSlashMenuItems(editor), insertTabs(editor)],
+            query,
+          )
+        }
+      />
+    </BlockNoteView>
+  );
+}