TypeCellOS · nperez0111 · May 5, 2026 · May 5, 2026 · May 5, 2026 · May 5, 2026
diff --git a/examples/06-custom-schema/01-alert-block/src/Alert.tsx b/examples/06-custom-schema/01-alert-block/src/Alert.tsx
@@ -60,6 +60,11 @@ export const createAlert = createReactBlockSpec(
  default: "warning",
  values: ["warning", "error", "info", "success"],
  },
+ title: {
+ default: undefined,
+ type: "string",
+ optional: true,
+ } as const,
  },
  content: "inline",
  },
@@ -69,6 +74,19 @@ export const createAlert = createReactBlockSpec(
  (a) => a.value === props.block.props.type,
  )!;
  const Icon = alertType.icon;
+ const savedTitle = props.block.props.title ?? "";
+
+ const saveTitle = (value: string) => {
+ const next = value.trim();
+ if (next === savedTitle) {
+ return;
+ }
+ props.editor.updateBlock(props.block, {
+ type: "alert",
+ props: { title: next || undefined },
+ });
+ };
+
  return (
  <div className={"alert"} data-alert-type={props.block.props.type}>
  {/*Icon which opens a menu to choose the Alert type*/}
@@ -111,8 +129,25 @@ export const createAlert = createReactBlockSpec(
  })}
  </Menu.Dropdown>
  </Menu>
- {/*Rich text field for user to type in*/}
- <div className={"inline-content"} ref={props.contentRef} />
+ <div className={"alert-body"}>
+ <div className={"alert-title-wrapper"} contentEditable={false}>
+ {/* This input can live within the block, and control the title property of the block */}
+ <input
+ key={savedTitle}
+ className={"alert-title-input"}
+ defaultValue={savedTitle}
+ placeholder="Add title"
+ onBlur={(e) => saveTitle(e.target.value)}
+ onKeyDown={(e) => {
+ if (e.key === "Enter") {
+ e.currentTarget.blur();
+ }
+ }}
+ />
+ </div>
+ {/*Rich text field for user to type in*/}
+ <div className={"inline-content"} ref={props.contentRef} />
+ </div>
  </div>
  );
  },

diff --git a/examples/06-custom-schema/01-alert-block/src/styles.css b/examples/06-custom-schema/01-alert-block/src/styles.css
@@ -72,3 +72,47 @@
 .inline-content {
  flex-grow: 1;
 }
+
+.alert-body {
+ display: flex;
+ flex-direction: column;
+ flex-grow: 1;
+ min-width: 0;
+}
+
+.alert-title-wrapper {
+ display: flex;
+ align-items: center;
+ min-height: 24px;
+}
+
+.alert-title-input {
+ background: transparent;
+ border: none;
+ border-radius: 3px;
+ color: inherit;
+ cursor: text;
+ font-family: inherit;
+ font-size: 0.9em;
+ font-weight: 600;
+ outline: none;
+ padding: 2px 4px;
+ width: 100%;
+}
+
+.alert-title-input::placeholder {
+ color: rgba(0, 0, 0, 0.35);
+ font-weight: 500;
+}
+
+[data-color-scheme="dark"] .alert-title-input::placeholder {
+ color: rgba(255, 255, 255, 0.4);
+}
+
+.alert-title-input:hover:not(:focus) {
+ background-color: rgba(0, 0, 0, 0.04);
+}
+
+[data-color-scheme="dark"] .alert-title-input:hover:not(:focus) {
+ background-color: rgba(255, 255, 255, 0.06);
+}
diff --git a/examples/06-custom-schema/09-macro-block/.bnexample.json b/examples/06-custom-schema/09-macro-block/.bnexample.json
@@ -0,0 +1,11 @@
+{
+ "playground": true,
+ "docs": true,
+ "author": "matthewlipski",
+ "tags": [
+ "Intermediate",
+ "Blocks",
+ "Custom Schemas"
+ ],
+ "dependencies": {}
+}
diff --git a/examples/06-custom-schema/09-macro-block/README.md b/examples/06-custom-schema/09-macro-block/README.md
@@ -0,0 +1,12 @@
+# Macro Block
+
+In this example, we create a custom `Macro` block using the vanilla `createBlockSpec` API from `@blocknote/core`. Each macro block stores an `id` prop, and the `id` is used to look up "before" and "after" HTML strings in a global map. Those strings are injected as html on either side of the editable inline content.
+
+This pattern is useful when you want a block whose decoration is driven by a runtime registry — for example, server-driven labels, citations, or templated wrappers.
+
+**Try it out:** Edit the inline text inside each macro block. Notice that the "before" and "after" decorations stay non-editable, and that swapping the `id` in `App.tsx` would change the surrounding HTML without touching the block's content.
+
+**Relevant Docs:**
+
+- [Custom Blocks](/docs/features/custom-schemas/custom-blocks)
+- [Editor Setup](/docs/getting-started/editor-setup)
diff --git a/examples/06-custom-schema/09-macro-block/index.html b/examples/06-custom-schema/09-macro-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>Macro 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/09-macro-block/main.tsx b/examples/06-custom-schema/09-macro-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/09-macro-block/package.json b/examples/06-custom-schema/09-macro-block/package.json
@@ -0,0 +1,30 @@
+{
+ "name": "@blocknote/example-custom-schema-macro-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"
+ },
+ "devDependencies": {
+ "@types/react": "^19.2.3",
+ "@types/react-dom": "^19.2.3",
+ "@vitejs/plugin-react": "^6.0.1",
+ "vite": "^8.0.8"
+ }
+}
diff --git a/examples/06-custom-schema/09-macro-block/src/App.tsx b/examples/06-custom-schema/09-macro-block/src/App.tsx
@@ -0,0 +1,44 @@
+import { BlockNoteSchema, defaultBlockSpecs } from "@blocknote/core";
+import "@blocknote/core/fonts/inter.css";
+import { BlockNoteView } from "@blocknote/mantine";
+import "@blocknote/mantine/style.css";
+import { useCreateBlockNote } from "@blocknote/react";
+
+import { macroBlock } from "./Macro";
+import "./styles.css";
+
+const schema = BlockNoteSchema.create({
+ blockSpecs: {
+ ...defaultBlockSpecs,
+ macro: macroBlock(),
+ },
+});
+
+export default function App() {
+ const editor = useCreateBlockNote({
+ schema,
+ initialContent: [
+ {
+ type: "paragraph",
+ content:
+ "Below are two macro blocks. Each looks up its before/after content from a global registry by id — the first uses HTML strings, the second uses a live <input> element:",
+ },
+ {
+ type: "macro",
+ props: { id: "warning" },
+ content: "Stay hydrated while editing",
+ },
+ {
+ type: "macro",
+ props: { id: "note" },
+ content: "Type a note here, then add a label on the left",
+ },
+ {
+ type: "paragraph",
+ content: "Edit the inline text inside each macro to see it stay live.",
+ },
+ ],
+ });
+
+ return <BlockNoteView editor={editor} />;
+}
diff --git a/examples/06-custom-schema/09-macro-block/src/Macro.ts b/examples/06-custom-schema/09-macro-block/src/Macro.ts
@@ -0,0 +1,63 @@
+import { createBlockSpec, defaultProps } from "@blocknote/core";
+
+import { macroRegistry } from "./macroRegistry";
+
+// The Macro block — built with the vanilla `createBlockSpec` API.
+//
+// It carries a single `id` prop that is used to look up the HTML that should
+// be rendered in the "before" and "after" slots around the block's editable
+// inline content. This can actually be in any structure, it is in your control
+export const macroBlock = createBlockSpec(
+ {
+ type: "macro",
+ propSchema: {
+ textAlignment: defaultProps.textAlignment,
+ textColor: defaultProps.textColor,
+ id: {
+ default: "" as const,
+ },
+ },
+ content: "inline",
+ },
+ {
+ render: (block) => {
+ const wrapper = document.createElement("div");
+ wrapper.className = "macro-block";
+
+ // We pull from the "registry" what this block should insert before and after
+ const definition = macroRegistry[block.props.id];
+
+ const before = document.createElement("div");
+ before.className = "macro-slot macro-slot-before";
+ before.contentEditable = "false";
+ const beforeContent = definition?.before ?? "";
+ if (typeof beforeContent === "string") {
+ before.innerHTML = beforeContent;
+ } else {
+ before.appendChild(beforeContent);
+ }
+
+ const content = document.createElement("div");
+ content.className = "macro-content";
+
+ const after = document.createElement("div");
+ after.className = "macro-slot macro-slot-after";
+ after.contentEditable = "false";
+ const afterContent = definition?.after ?? "";
+ if (typeof afterContent === "string") {
+ after.innerHTML = afterContent;
+ } else {
+ after.appendChild(afterContent);
+ }
+
+ // You have full control over this HTML structure
+ // and can inject the rich-text content wherever you want
+ wrapper.append(before, content, after);
+
+ return {
+ dom: wrapper,
+ contentDOM: content,
+ };
+ },
+ },
+);
diff --git a/examples/06-custom-schema/09-macro-block/src/macroRegistry.ts b/examples/06-custom-schema/09-macro-block/src/macroRegistry.ts
@@ -0,0 +1,48 @@
+// A global, runtime-mutable registry that maps a macro id to the content that
+// should be injected before and after the block's editable inline content.
+//
+// Each slot can be either:
+// - an HTML string → injected via innerHTML
+// - an HTMLElement → injected via appendChild (lets you put live, stateful
+// DOM into the slot — e.g. an <input>)
+//
+// In a real application this could be populated from a server response, a
+// shared module, or any other side channel — the block render function only
+// reads from it.
+export type MacroDefinition = {
+ before: string | HTMLElement;
+ after: string | HTMLElement;
+};
+
+// An interactive "before" slot: a real <input> that lives in the registry and
+// gets appended into whichever macro block uses this id. This mirrors the
+// pattern from the Alert block's title input — but here it's authored as
+// vanilla DOM and managed by the registry rather than by React state.
+const labelInput = document.createElement("input");
+labelInput.className = "macro-label-input";
+labelInput.type = "text";
+labelInput.placeholder = "Label…";
+labelInput.setAttribute("aria-label", "Macro label");
+
+export const macroRegistry: Record<string, MacroDefinition> = {
+ warning: {
+ before: `
+ <span class="macro-badge macro-badge-warning">
+ <span class="macro-emoji">⚠️</span>
+ Heads up
+ </span>
+ `,
+ after: `
+ <a class="macro-link" href="https://www.blocknotejs.org/" target="_blank" rel="noreferrer">
+ Read the docs →
+ </a>
+ `,
+ },
+ note: {
+ // An HTMLElement instead of a string — the macro block will appendChild it.
+ before: labelInput,
+ after: `
+ <span class="macro-meta">— the input on the left is a live DOM node</span>
+ `,
+ },
+};