From f7dc7faa65bc362c77c386e01810233ca1431e0b Mon Sep 17 00:00:00 2001
From: Peter White <1788320+peterwhite@users.noreply.github.com>
Date: Wed, 14 Oct 2026 08:25:57 +0200
Subject: [PATCH] Reserve webframe size before hydration (#4683)

---
 .../webframe-reserve-size-before-mount.md     |  6 ++++
 .../DocumentView/Integration/contentkit.css   |  8 +++++
 .../react-contentkit/src/ElementWebframe.tsx  | 36 +++++++++----------
 3 files changed, 32 insertions(+), 18 deletions(-)
 create mode 100644 .changeset/webframe-reserve-size-before-mount.md

diff --git a/.changeset/webframe-reserve-size-before-mount.md b/.changeset/webframe-reserve-size-before-mount.md
new file mode 100644
index 000000000..c32db756c
--- /dev/null
+++ b/.changeset/webframe-reserve-size-before-mount.md
@@ -0,0 +1,6 @@
+---
+"@gitbook/react-contentkit": patch
+"gitbook": patch
+---
+
+Reserve the webframe's size in the server-rendered layout so anchor links to content below integration blocks no longer land too high.
diff --git a/packages/gitbook/src/components/DocumentView/Integration/contentkit.css b/packages/gitbook/src/components/DocumentView/Integration/contentkit.css
index ca74cba1e..dd8ff8e50 100644
--- a/packages/gitbook/src/components/DocumentView/Integration/contentkit.css
+++ b/packages/gitbook/src/components/DocumentView/Integration/contentkit.css
@@ -52,6 +52,14 @@
     @apply relative;
 }
 
+.contentkit-webframe-container {
+    @apply relative;
+}
+
+.contentkit-webframe-loading {
+    @apply absolute inset-0 m-auto size-5 animate-spin;
+}
+
 /** Card */
 .contentkit-card {
     @apply flex flex-col border rounded border-tint-subtle;
diff --git a/packages/react-contentkit/src/ElementWebframe.tsx b/packages/react-contentkit/src/ElementWebframe.tsx
index 62c31c6d3..229fe93bf 100644
--- a/packages/react-contentkit/src/ElementWebframe.tsx
+++ b/packages/react-contentkit/src/ElementWebframe.tsx
@@ -152,7 +152,7 @@ export function ElementWebframe(props: ContentKitClientElementProps<ContentKitWe
 
         window.addEventListener('message', callback);
 
-        // We only render the iframe once we have added the event listener
+        // We only load the iframe once we have added the event listener
         // otherwise during SSR, we'll miss messages
         setMounted(true);
 
@@ -186,27 +186,27 @@ export function ElementWebframe(props: ContentKitClientElementProps<ContentKitWe
             ? iframeRef.current.clientWidth / height
             : undefined);
 
-    if (!mounted) {
-        return <Icon icon="spinner" className="contentkit-button-loading" style={{ height }} />;
-    }
-
     // only use height measurement if no aspect ratio is defined
     const useHeightMeasurement = !aspectRatio && height;
 
     return (
-        <iframe
-            ref={iframeRef}
-            src={element.source.url}
-            title={element.source.url}
-            allowFullScreen
-            allow="clipboard-write"
-            className="contentkit-webframe h-full w-full max-w-full border-none"
-            style={{
-                aspectRatio,
-                height: useHeightMeasurement ? height : undefined,
-                maxHeight: height,
-            }}
-        />
+        <div className="contentkit-webframe-container h-full w-full max-w-full">
+            <iframe
+                ref={iframeRef}
+                // Rendered without a source before mount so it reserves its size in the SSR layout.
+                src={mounted ? element.source.url : undefined}
+                title={element.source.url}
+                allowFullScreen
+                allow="clipboard-write"
+                className="contentkit-webframe block h-full w-full max-w-full border-none"
+                style={{
+                    aspectRatio,
+                    height: useHeightMeasurement ? height : undefined,
+                    maxHeight: height,
+                }}
+            />
+            {mounted ? null : <Icon icon="spinner" className="contentkit-webframe-loading" />}
+        </div>
     );
 }