GitbookIO · nolannbiron · Jun 7, 2025 · Jun 7, 2025 · Jun 7, 2025 · Jun 8, 2025
diff --git a/.changeset/sweet-hornets-change.md b/.changeset/sweet-hornets-change.md
@@ -0,0 +1,5 @@
+---
+'gitbook': minor
+---
+
+Revamp mobile navigation
diff --git a/bun.lock b/bun.lock
diff --git a/packages/gitbook/package.json b/packages/gitbook/package.json
@@ -28,6 +28,7 @@
         "@gitbook/react-math": "workspace:*",
         "@gitbook/react-openapi": "workspace:*",
         "@radix-ui/react-checkbox": "^1.0.4",
+        "@radix-ui/react-dialog": "^1.1.14",
         "@radix-ui/react-dropdown-menu": "^2.1.12",
         "@radix-ui/react-navigation-menu": "^1.2.3",
         "@radix-ui/react-popover": "^1.0.7",

diff --git a/packages/gitbook/src/components/Header/DropdownMenu.tsx b/packages/gitbook/src/components/Header/DropdownMenu.tsx
@@ -7,6 +7,7 @@ import { useState } from 'react';
 import { type ClassValue, tcls } from '@/lib/tailwind';
 
 import * as RadixDropdownMenu from '@radix-ui/react-dropdown-menu';
+import { Slot } from '@radix-ui/react-slot';
 
 import { Link, type LinkInsightsProps } from '../primitives';
 
@@ -25,13 +26,21 @@ export function DropdownMenu(props: {
     children: React.ReactNode;
     /** Custom styles */
     className?: ClassValue;
-    /** Open the dropdown on hover */
+    /** Open the dropdown on hover
+     * @default false
+     */
     openOnHover?: boolean;
+    /** Whether to render the dropdown menu in a portal
+     * @default true
+     */
+    withPortal?: boolean;
 }) {
-    const { button, children, className, openOnHover = false } = props;
+    const { button, children, className, openOnHover = false, withPortal = true } = props;
     const [hovered, setHovered] = useState(false);
     const [clicked, setClicked] = useState(false);
 
+    const Portal = withPortal ? RadixDropdownMenu.Portal : Slot;
+
     return (
         <RadixDropdownMenu.Root
             modal={false}
@@ -48,15 +57,16 @@ export function DropdownMenu(props: {
                 {button}
             </RadixDropdownMenu.Trigger>
 
-            <RadixDropdownMenu.Portal>
+            <Portal>
                 <RadixDropdownMenu.Content
                     data-testid="dropdown-menu"
                     hideWhenDetached
                     collisionPadding={8}
                     onMouseEnter={() => setHovered(true)}
                     onMouseLeave={() => setHovered(false)}
                     align="start"
-                    className="z-40 animate-present pt-2"
+                    sideOffset={8}
+                    className="z-40 animate-present"
                 >
                     <div
                         className={tcls(
@@ -67,7 +77,7 @@ export function DropdownMenu(props: {
                         {children}
                     </div>
                 </RadixDropdownMenu.Content>
-            </RadixDropdownMenu.Portal>
+            </Portal>
         </RadixDropdownMenu.Root>
     );
 }

diff --git a/packages/gitbook/src/components/Header/Header.tsx b/packages/gitbook/src/components/Header/Header.tsx
@@ -11,7 +11,7 @@ import { HeaderLink } from './HeaderLink';
 import { HeaderLinkMore } from './HeaderLinkMore';
 import { HeaderLinks } from './HeaderLinks';
 import { HeaderLogo } from './HeaderLogo';
-import { HeaderMobileMenu } from './HeaderMobileMenu';
+import { HeaderMobileMenuButton } from './HeaderMobileMenuButton';
 import { SpacesDropdown } from './SpacesDropdown';
 
 /**
@@ -76,7 +76,7 @@ export function Header(props: { context: GitBookSiteContext; withTopHeader?: boo
                                 'min-w-0 shrink items-center justify-start gap-2 lg:gap-4'
                             )}
                         >
-                            <HeaderMobileMenu
+                            <HeaderMobileMenuButton
                                 className={tcls(
                                     'lg:hidden',
                                     '-ml-2',

diff --git a/packages/gitbook/src/components/Header/HeaderMobileMenu.tsx b/packages/gitbook/src/components/Header/HeaderMobileMenu.tsx
diff --git a/packages/gitbook/src/components/Header/HeaderMobileMenuButton.tsx b/packages/gitbook/src/components/Header/HeaderMobileMenuButton.tsx
@@ -0,0 +1,35 @@
+'use client';
+
+import { Icon } from '@gitbook/icons';
+
+import { useMobileMenuSheet } from '@/components/MobileMenu/useMobileMenuSheet';
+import { tString, useLanguage } from '@/intl/client';
+import { tcls } from '@/lib/tailwind';
+
+/**
+ * Button to show/hide the table of content on mobile.
+ */
+export function HeaderMobileMenuButton(
+    props: Partial<React.ButtonHTMLAttributes<HTMLButtonElement>>
+) {
+    const language = useLanguage();
+    const { open, setOpen } = useMobileMenuSheet();
+
+    const toggleNavigation = () => {
+        setOpen(!open);
+    };
+
+    return (
+        <button
+            {...props}
+            aria-label={tString(language, 'table_of_contents_button_label')}
+            onClick={toggleNavigation}
+            className={tcls(
+                'flex flex-row items-center rounded straight-corners:rounded-sm px-2 py-1',
+                props.className
+            )}
+        >
+            <Icon icon="bars" className="size-4 text-inherit" />
+        </button>
+    );
+}
diff --git a/packages/gitbook/src/components/Header/SpacesDropdown.tsx b/packages/gitbook/src/components/Header/SpacesDropdown.tsx
@@ -11,15 +11,17 @@ export function SpacesDropdown(props: {
     siteSpace: SiteSpace;
     siteSpaces: SiteSpace[];
     className?: string;
+    withPortal?: boolean;
 }) {
-    const { context, siteSpace, siteSpaces, className } = props;
+    const { context, siteSpace, siteSpaces, className, withPortal } = props;
 
     return (
         <DropdownMenu
             className={tcls(
                 'group-hover/dropdown:invisible', // Prevent hover from opening the dropdown, as it's annoying in this context
                 'group-focus-within/dropdown:group-hover/dropdown:visible' // When the dropdown is already open, it should remain visible when hovered
             )}
+            withPortal={withPortal}
             button={
                 <div
                     data-testid="space-dropdown-button"

diff --git a/packages/gitbook/src/components/MobileMenu/MobileMenuScript.tsx b/packages/gitbook/src/components/MobileMenu/MobileMenuScript.tsx
@@ -0,0 +1,26 @@
+'use client';
+
+import { useMobileMenuSheet } from '@/components/MobileMenu';
+import { usePathname } from 'next/navigation';
+import { useEffect } from 'react';
+
+export function MobileMenuScript() {
+    const pathname = usePathname();
+    const { open, setOpen } = useMobileMenuSheet();
+
+    // biome-ignore lint/correctness/useExhaustiveDependencies: Close the navigation when navigating to a page
+    useEffect(() => {
+        setOpen(false);
+    }, [pathname]);
+
+    useEffect(() => {
+        // If the menu is open, we add a class to the body to prevent scrolling
+        if (open) {
+            document.body.style.overflow = 'hidden';
+        } else {
+            document.body.style.overflow = 'auto';
+        }
+    }, [open]);
+
+    return null;
+}
diff --git a/packages/gitbook/src/components/MobileMenu/index.ts b/packages/gitbook/src/components/MobileMenu/index.ts
@@ -0,0 +1,2 @@
+export * from './useMobileMenuSheet';
+export * from './MobileMenuScript';
diff --git a/packages/gitbook/src/components/MobileMenu/useMobileMenuSheet.ts b/packages/gitbook/src/components/MobileMenu/useMobileMenuSheet.ts
@@ -0,0 +1,12 @@
+import { create } from 'zustand';
+
+/**
+ * Hooks to manage the mobile menu sheet state.
+ */
+export const useMobileMenuSheet = create<{
+    open: boolean;
+    setOpen: (open: boolean) => void;
+}>((set) => ({
+    open: false,
+    setOpen: (open) => set({ open }),
+}));
diff --git a/packages/gitbook/src/components/SpaceLayout/SpaceLayout.tsx b/packages/gitbook/src/components/SpaceLayout/SpaceLayout.tsx
@@ -5,13 +5,13 @@ import React from 'react';
 import { Footer } from '@/components/Footer';
 import { Header, HeaderLogo } from '@/components/Header';
 import { SearchButton, SearchModal } from '@/components/Search';
-import { TableOfContents } from '@/components/TableOfContents';
+import { TOCScrollContent, TableOfContents } from '@/components/TableOfContents';
 import { CONTAINER_STYLE } from '@/components/layout';
 import { getSpaceLanguage } from '@/intl/server';
 import { t } from '@/intl/translate';
+import type { VisitorAuthClaims } from '@/lib/adaptive';
 import { tcls } from '@/lib/tailwind';
 
-import type { VisitorAuthClaims } from '@/lib/adaptive';
 import { GITBOOK_API_PUBLIC_URL, GITBOOK_APP_URL } from '@v2/lib/env';
 import { Announcement } from '../Announcement';
 import { SpacesDropdown } from '../Header/SpacesDropdown';
@@ -81,7 +81,6 @@ export function SpaceLayout(props: {
                         )}
                     >
                         <TableOfContents
-                            context={context}
                             header={
                                 withTopHeader ? null : (
                                     <div
@@ -99,47 +98,61 @@ export function SpaceLayout(props: {
                                     </div>
                                 )
                             }
-                            innerHeader={
-                                // displays the search button and/or the space dropdown in the ToC according to the header/variant settings. E.g if there is no header, the search button will be displayed in the ToC.
-                                <>
-                                    {!withTopHeader && (
-                                        <div className={tcls('hidden', 'lg:block')}>
-                                            <React.Suspense fallback={null}>
-                                                <SearchButton>
-                                                    <span className={tcls('flex-1')}>
-                                                        {t(
-                                                            getSpaceLanguage(customization),
-                                                            customization.aiSearch.enabled
-                                                                ? 'search_or_ask'
-                                                                : 'search'
-                                                        )}
-                                                        ...
-                                                    </span>
-                                                </SearchButton>
-                                            </React.Suspense>
-                                        </div>
-                                    )}
-                                    {!withTopHeader && withSections && sections && (
-                                        <SiteSectionList
-                                            className={tcls('hidden', 'lg:block')}
-                                            sections={encodeClientSiteSections(context, sections)}
-                                        />
-                                    )}
-                                    {isMultiVariants && (
-                                        <SpacesDropdown
-                                            context={context}
-                                            siteSpace={siteSpace}
-                                            siteSpaces={siteSpaces}
-                                            className={tcls(
-                                                'w-full',
-                                                'page-no-toc:hidden',
-                                                'site-header-none:page-no-toc:flex'
+                        >
+                            <TOCScrollContent
+                                context={context}
+                                innerHeader={
+                                    !withTopHeader || isMultiVariants ? (
+                                        // displays the search button and/or the space dropdown in the ToC according to the header/variant settings. E.g if there is no header, the search button will be displayed in the ToC.
+                                        <>
+                                            {!withTopHeader && (
+                                                <div className={tcls('hidden', 'lg:block')}>
+                                                    <React.Suspense fallback={null}>
+                                                        <SearchButton>
+                                                            <span className={tcls('flex-1')}>
+                                                                {t(
+                                                                    getSpaceLanguage(customization),
+                                                                    customization.aiSearch.enabled
+                                                                        ? 'search_or_ask'
+                                                                        : 'search'
+                                                                )}
+                                                                ...
+                                                            </span>
+                                                        </SearchButton>
+                                                    </React.Suspense>
+                                                </div>
                                             )}
-                                        />
-                                    )}
-                                </>
-                            }
-                        />
+                                            {!withTopHeader && withSections && sections && (
+                                                <SiteSectionList
+                                                    className={tcls('hidden', 'lg:block')}
+                                                    sections={encodeClientSiteSections(
+                                                        context,
+                                                        sections
+                                                    )}
+                                                />
+                                            )}
+                                            {isMultiVariants && (
+                                                <SpacesDropdown
+                                                    /** Needed to avoid the dropdown being rendered in the wrong place when the mobile menu is open. */
+                                                    withPortal={false}
+                                                    context={context}
+                                                    siteSpace={siteSpace}
+                                                    siteSpaces={siteSpaces}
+                                                    className={tcls(
+                                                        'w-full',
+                                                        'page-no-toc:hidden',
+                                                        'site-header-none:page-no-toc:flex',
+                                                        'mb-2',
+                                                        // Set the height to match the close button of the mobile menu sheet
+                                                        'max-lg:h-8'
+                                                    )}
+                                                />
+                                            )}
+                                        </>
+                                    ) : null
+                                }
+                            />
+                        </TableOfContents>
                         <div className="flex min-w-0 flex-1 flex-col">{children}</div>
                     </div>
                 </div>

diff --git a/packages/gitbook/src/components/TableOfContents/PageGroupItem.tsx b/packages/gitbook/src/components/TableOfContents/PageGroupItem.tsx
@@ -29,8 +29,8 @@ export function PageGroupItem(props: {
                     '[html.sidebar-filled.theme-bold.tint_&]:bg-tint-subtle',
                     '[html.sidebar-filled.theme-muted_&]:bg-tint-base',
                     '[html.sidebar-filled.theme-bold.tint_&]:bg-tint-base',
-                    '[html.sidebar-default.theme-gradient_&]:bg-gradient-primary',
-                    '[html.sidebar-default.theme-gradient.tint_&]:bg-gradient-tint'
+                    'lg:[html.sidebar-default.theme-gradient_&]:bg-gradient-primary',
+                    'lg:[html.sidebar-default.theme-gradient.tint_&]:bg-gradient-tint'
                 )}
             >
                 <TOCPageIcon page={page} />
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		export * from './useMobileMenuSheet';
		export * from './MobileMenuScript';