From 2deb2224e3e21cf4e916b25cfdbb396839343660 Mon Sep 17 00:00:00 2001
From: Tomek Gargula <tomasz@gitbook.com>
Date: Fri, 18 Sep 2026 16:49:28 +0200
Subject: [PATCH] Fix sticky table of contents scrolling

---
 .../src/components/TableOfContents/PageGroupItem.tsx      | 8 ++++----
 .../src/components/TableOfContents/TableOfContents.tsx    | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/gitbook/src/components/TableOfContents/PageGroupItem.tsx b/packages/gitbook/src/components/TableOfContents/PageGroupItem.tsx
index 3eae81fe1..7eeca28cd 100644
--- a/packages/gitbook/src/components/TableOfContents/PageGroupItem.tsx
+++ b/packages/gitbook/src/components/TableOfContents/PageGroupItem.tsx
@@ -34,9 +34,8 @@ export function PageGroupItem(props: { page: ClientTOCPageGroup; isFirst?: boole
         >
             <div
                 className={tcls(
-                    // Pinned below the sidebar's 16px top fade (ScrollContainer's `mask-t-from-*`),
-                    // so a stuck header is never rendered inside the band that fades it out.
-                    'top-4 sticky z-1',
+                    // Keep the group at the same vertical position as the original sidebar layout.
+                    '-top-4 sticky z-1',
                     'bg-tint-base',
                     'sidebar-filled:bg-tint-subtle',
                     'theme-muted:bg-tint-subtle',
@@ -92,7 +91,8 @@ export function PageGroupItem(props: { page: ClientTOCPageGroup; isFirst?: boole
                         isOpen ? 'grid-rows-[1fr] opacity-100' : 'grid-rows-[0fr] opacity-0'
                     )}
                 >
-                    <div className="overflow-hidden">
+                    {/* Clip only while closed so open descendant headers can stick to the main scrollport. */}
+                    <div className={tcls('min-h-0', isOpen ? 'overflow-visible' : 'overflow-clip')}>
                         <PagesList pages={descendants} />
                     </div>
                 </div>
diff --git a/packages/gitbook/src/components/TableOfContents/TableOfContents.tsx b/packages/gitbook/src/components/TableOfContents/TableOfContents.tsx
index 87f8265d4..0e20ed6d2 100644
--- a/packages/gitbook/src/components/TableOfContents/TableOfContents.tsx
+++ b/packages/gitbook/src/components/TableOfContents/TableOfContents.tsx
@@ -132,7 +132,7 @@ export async function TableOfContents(props: {
                     <ScrollContainer
                         data-testid="toc-scroll-container"
                         orientation="vertical"
-                        // `pt-4` matches the page-group headers' sticky offset, so the first group rests on it.
+                        // Leave room for the first group below the scrollport's top fade.
                         contentClassName="flex flex-col p-2 pt-4 gutter-stable"
                         active="[data-active=true]"
                         leading={{