Skip to content

Commit a235126

Browse files
nperez0111nperez0111
committed
feat(react): configurable portal targets for floating UI
Adds a `portalElements` prop on `BlockNoteView` for configuring where floating UI elements (slash menu, formatting toolbar, side menu, table handles, etc) portal to, plus a per-Controller `portalElement` override. Also changes `editor.mount()` to default to `element.parentElement` (i.e. `bn-container`) instead of `document.body` so floating UI is contained within the editor by default. Pass `portalElements={{ default: document.body }}` to opt back into the previous behaviour. Resolves #2692.
1 parent 1b53232 commit a235126

28 files changed

Lines changed: 608 additions & 29 deletions

‎examples/03-ui-components/20-portal-elements/.bnexample.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"playground": true,
3+
"docs": true,
4+
"author": "nperez0111",
5+
"tags": ["UI Components", "Advanced"]
6+
}

‎examples/03-ui-components/20-portal-elements/README.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Configuring Portal Targets per Element
2+
3+
By default, BlockNote's floating UI elements (formatting toolbar, slash menu, table handles, etc.) mount inside the editor's `bn-container` element. The `portalElements` prop lets you change that — globally via `default`, or per element by key.
4+
5+
In this example we deliberately wrap the editor in a small parent with `overflow: hidden` so the global default of `bn-container` would clip the slash menu and the formatting toolbar. We escape only those two to `document.body`, while keeping `tableHandles` inside `.bn-container` so the table handles can never escape the editor's visual boundary.
6+
7+
```tsx
8+
<BlockNoteView
9+
editor={editor}
10+
portalElements={{
11+
slashMenu: document.body,
12+
formattingToolbar: document.body,
13+
tableHandles: ".bn-container",
14+
}}
15+
/>
16+
```
17+
18+
**Relevant Docs:**
19+
20+
- [UI Components](/docs/react/components)

‎examples/03-ui-components/20-portal-elements/index.html‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
<html lang="en">
2+
<head>
3+
<meta charset="UTF-8" />
4+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
5+
<title>Configuring Portal Targets per Element</title>
6+
<script>
7+
<!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->
8+
</script>
9+
</head>
10+
<body>
11+
<div id="root"></div>
12+
<script type="module" src="./main.tsx"></script>
13+
</body>
14+
</html>

‎examples/03-ui-components/20-portal-elements/main.tsx‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
// AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY
2+
import React from "react";
3+
import { createRoot } from "react-dom/client";
4+
import App from "./src/App.jsx";
5+
6+
const root = createRoot(document.getElementById("root")!);
7+
root.render(
8+
<React.StrictMode>
9+
<App />
10+
</React.StrictMode>
11+
);

‎examples/03-ui-components/20-portal-elements/package.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{
2+
"name": "@blocknote/example-ui-components-portal-elements",
3+
"description": "AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY",
4+
"type": "module",
5+
"private": true,
6+
"version": "0.12.4",
7+
"scripts": {
8+
"start": "vite",
9+
"dev": "vite",
10+
"build:prod": "tsc && vite build",
11+
"preview": "vite preview"
12+
},
13+
"dependencies": {
14+
"@blocknote/ariakit": "latest",
15+
"@blocknote/core": "latest",
16+
"@blocknote/mantine": "latest",
17+
"@blocknote/react": "latest",
18+
"@blocknote/shadcn": "latest",
19+
"@mantine/core": "^9.0.2",
20+
"@mantine/hooks": "^9.0.2",
21+
"react": "^19.2.3",
22+
"react-dom": "^19.2.3"
23+
},
24+
"devDependencies": {
25+
"@types/react": "^19.2.3",
26+
"@types/react-dom": "^19.2.3",
27+
"@vitejs/plugin-react": "^6.0.1",
28+
"vite": "^8.0.8"
29+
}
30+
}

‎examples/03-ui-components/20-portal-elements/src/App.tsx‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
import "@blocknote/core/fonts/inter.css";
2+
import { BlockNoteView } from "@blocknote/mantine";
3+
import "@blocknote/mantine/style.css";
4+
import { useCreateBlockNote, type PortalElementsMap } from "@blocknote/react";
5+
6+
import "./styles.css";
7+
8+
const initialContent = [
9+
{
10+
type: "paragraph" as const,
11+
content: "Click in this editor and press / to open the slash menu.",
12+
},
13+
{
14+
type: "paragraph" as const,
15+
content:
16+
"Notice whether the menu fits inside the box or escapes it.",
17+
},
18+
{
19+
type: "paragraph" as const,
20+
},
21+
];
22+
23+
function PortalDemoEditor({
24+
label,
25+
description,
26+
portalElements,
27+
}: {
28+
label: string;
29+
description: string;
30+
portalElements?: PortalElementsMap;
31+
}) {
32+
const editor = useCreateBlockNote({ initialContent });
33+
return (
34+
<div className="view-wrapper">
35+
<div className="view-label">{label}</div>
36+
<div className="view-description">{description}</div>
37+
<div className="view">
38+
<BlockNoteView editor={editor} portalElements={portalElements} />
39+
</div>
40+
</div>
41+
);
42+
}
43+
44+
export default function App() {
45+
return (
46+
<div className="views">
47+
<PortalDemoEditor
48+
label="Default — clipped"
49+
description="No portalElements prop. Floating UI mounts inside .bn-container — the slash menu is clipped by the editor's bounds."
50+
/>
51+
<PortalDemoEditor
52+
label="portalElements={{ default: document.body }} — escapes"
53+
description="Every floating UI element escapes the editor container and renders directly under <body>."
54+
portalElements={{ default: document.body }}
55+
/>
56+
</div>
57+
);
58+
}

‎examples/03-ui-components/20-portal-elements/src/styles.css‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
.views {
2+
container-name: views;
3+
container-type: inline-size;
4+
display: flex;
5+
flex-direction: row;
6+
flex-wrap: wrap;
7+
gap: 8px;
8+
padding: 8px;
9+
}
10+
11+
/*
12+
* Each view is intentionally shorter than the slash menu so the clipping
13+
* vs escaping behaviour is visible at a glance.
14+
*/
15+
.view-wrapper {
16+
display: flex;
17+
flex-direction: column;
18+
height: 260px;
19+
width: 100%;
20+
}
21+
22+
@container views (width > 1024px) {
23+
.view-wrapper {
24+
width: calc(50% - 4px);
25+
}
26+
}
27+
28+
.view-label {
29+
color: #0090ff;
30+
display: flex;
31+
font-size: 12px;
32+
font-weight: bold;
33+
justify-content: space-between;
34+
margin-inline: 16px;
35+
}
36+
37+
.view-description {
38+
color: #0090ff;
39+
font-size: 12px;
40+
margin: 2px 16px 0;
41+
}
42+
43+
/*
44+
* `position: relative` is what actually makes `overflow: hidden` clip the
45+
* absolutely-positioned floating UI. Without it the popover's containing
46+
* block is the viewport and the clip is bypassed.
47+
*/
48+
.view {
49+
border: solid #0090ff 1px;
50+
border-radius: 16px;
51+
flex: 1;
52+
height: 0;
53+
padding: 8px;
54+
position: relative;
55+
overflow: hidden;
56+
}
57+
58+
.view .bn-container {
59+
height: 100%;
60+
margin: 0;
61+
max-width: none;
62+
padding: 0;
63+
}
64+
65+
.view .bn-editor {
66+
height: 100%;
67+
overflow: auto;
68+
}

‎examples/03-ui-components/20-portal-elements/tsconfig.json‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
{
2+
"__comment": "AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY",
3+
"compilerOptions": {
4+
"target": "ESNext",
5+
"useDefineForClassFields": true,
6+
"lib": [
7+
"DOM",
8+
"DOM.Iterable",
9+
"ESNext"
10+
],
11+
"allowJs": false,
12+
"skipLibCheck": true,
13+
"esModuleInterop": false,
14+
"allowSyntheticDefaultImports": true,
15+
"strict": true,
16+
"forceConsistentCasingInFileNames": true,
17+
"module": "ESNext",
18+
"moduleResolution": "bundler",
19+
"resolveJsonModule": true,
20+
"isolatedModules": true,
21+
"noEmit": true,
22+
"jsx": "react-jsx",
23+
"composite": true
24+
},
25+
"include": [
26+
"."
27+
],
28+
"__ADD_FOR_LOCAL_DEV_references": [
29+
{
30+
"path": "../../../packages/core/"
31+
},
32+
{
33+
"path": "../../../packages/react/"
34+
}
35+
]
36+
}

‎examples/03-ui-components/20-portal-elements/vite.config.ts‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
// AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY
2+
import react from "@vitejs/plugin-react";
3+
import * as fs from "fs";
4+
import * as path from "path";
5+
import { defineConfig } from "vite";
6+
// import eslintPlugin from "vite-plugin-eslint";
7+
// https://vitejs.dev/config/
8+
export default defineConfig((conf) => ({
9+
plugins: [react()],
10+
optimizeDeps: {},
11+
build: {
12+
sourcemap: true,
13+
},
14+
resolve: {
15+
alias:
16+
conf.command === "build" ||
17+
!fs.existsSync(path.resolve(__dirname, "../../packages/core/src"))
18+
? {}
19+
: ({
20+
// Comment out the lines below to load a built version of blocknote
21+
// or, keep as is to load live from sources with live reload working
22+
"@blocknote/core": path.resolve(
23+
__dirname,
24+
"../../packages/core/src/"
25+
),
26+
"@blocknote/react": path.resolve(
27+
__dirname,
28+
"../../packages/react/src/"
29+
),
30+
} as any),
31+
},
32+
}));

‎packages/core/src/editor/BlockNoteEditor.ts‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -731,15 +731,27 @@ export class BlockNoteEditor<
731731
/**
732732
* Mount the editor to a DOM element.
733733
*
734+
* @param element The DOM element to mount the editor's contenteditable into.
735+
* @param options.portalTarget Where to mount `editor.portalElement` — the
736+
* container that floating UI (toolbars, menus, etc) portals into. When
737+
* omitted, defaults to `element.parentElement` (which is the editor's
738+
* `bn-container` in typical React usage), or to `document.body` /
739+
* the surrounding shadow root when no parent is available.
740+
*
734741
* @warning Not needed to call manually when using React, use BlockNoteView to take care of mounting
735742
*/
736-
public mount = (element: HTMLElement) => {
743+
public mount = (
744+
element: HTMLElement,
745+
options?: { portalTarget?: HTMLElement | null },
746+
) => {
737747
const root = element.getRootNode();
738-
if (typeof ShadowRoot !== "undefined" && root instanceof ShadowRoot) {
739-
root.appendChild(this.portalElement);
740-
} else {
741-
document.body.appendChild(this.portalElement);
742-
}
748+
const isInShadowRoot =
749+
typeof ShadowRoot !== "undefined" && root instanceof ShadowRoot;
750+
const target =
751+
options?.portalTarget ??
752+
element.parentElement ??
753+
(isInShadowRoot ? (root as ShadowRoot) : document.body);
754+
target.appendChild(this.portalElement);
743755
this._tiptapEditor.mount({ mount: element });
744756
};
745757

0 commit comments

Comments
 (0)