Anchor links inside mobile hamburger menu do not scroll to target (URL updates, scroll does not)

[pleasenophp]

Search terms

mobile anchor links, hamburger menu, hash navigation, scroll not working, iOS Safari, iOS Chrome, default theme, README anchors, sidebar navigation

Expected Behavior

When clicking an anchor link (e.g. #some-header) inside the hamburger menu on mobile:

• The hamburger menu should close.
• The page should scroll to the corresponding anchor target.

This is how the behavior already works on desktop.

Actual Behavior

On real mobile devices only (tested on iOS Safari and iOS Chrome):

• Clicking an anchor link inside the hamburger menu updates the URL correctly.
• The hamburger menu closes correctly, including its animation.
• ❗ The page does NOT scroll to the anchor target.
• The scroll position remains unchanged.

This issue:

• ✅ Happens on real mobile devices

• ❌ Does NOT happen on desktop

• ❌ Does NOT happen in desktop DevTools mobile emulation

• The issue was reproduced WITHOUT any plugins enabled.

• The issue was reproduced with default theme, and also with other different theme plugins. The only theme from the ones I tried, where this issue was not happening, was this one: https://www.npmjs.com/package/typedoc-material-theme

Steps to reproduce the bug

1. Create a long README.md file with multiple headers far apart so that some are outside the initial viewport, for example:

   ## Some header 1
   (a lot of content...)
   
   ## Some header 2
   (a lot of content...)
   
   ## Some header 3
   (a lot of content...)
   

2. Configure typedoc.json, using the default theme, no plugins, and include the README:

"readme": "README.md",
"theme": "default"

3. Run TypeDoc to generate, and publish it somewhere to access from the mobile phone.

4. On a real mobile device:

• Open the generated documentation.
• Open the hamburger menu.
• Scroll inside the menu.
• Tap a link that points to a header not currently visible in the viewport.

Result

• The hamburger menu closes.
• The URL updates with the correct anchor.
• The page does not scroll to the anchor.

Workaround

As a temporary workaround, I disabled the scroll lock applied to the body when the hamburger menu is open by adding custom CSS.

typedoc.json:

{
  ...
  "customCss": "./typedoc-custom.css"
}

typedoc-custom.css:

.has-menu body {
  overflow: visible !important;
}

Configs, that might be relevant

package.json:

{
  "name": "redacted",
  "version": "redacted",
  "description": "redacted",
  "author": "redacted",
  "license": "redacted",
  "scripts": {
       "redacted": ""
  },
  "devDependencies": {
    "dotenv": "^17.2.3",
    "mustache": "^4.2.0",
    "typedoc": "^0.28.15"
  }
}

tsconfig.typedoc.json:

{
  "compilerOptions": {
    "checkJs": false,
    "baseUrl": ".",
    "typeRoots": ["./srcjs/types"],
    "lib": ["esnext", "dom"]
  },
  "include": ["./srcjs/types/*.d.ts"]
}

typedoc.json (before the workaround):

{
  "$schema": "https://typedoc.org/schema.json",
  "tsconfig": "tsconfig.typedoc.json",
  "name": "redacted",
  "entryPoints": [
    "srcjs/types/global.d.ts",
    "...redacted"
  ],
  "sort": ["visibility", "kind", "instance-first", "alphabetical-ignoring-documents"],
  "sortEntryPoints": false,
  "readme": "README.md",
  "exclude": ["**/redacted.d.ts"],
  "out": "docs",
  "excludeExternals": false,
  "excludeInternal": false,
  "excludePrivate": false,
  "excludeProtected": false,
  "highlightLanguages": ["typescript", "javascript", "cpp", "bash", "json", "cmd"],
  "navigationLinks": {
     "redacted": "https://example.com",
     "redacted": "more links..."
  }
}

Running typedoc with:

npx typedoc

Environment

TypeDoc version: 0.28.15 (latest)
TypeScript version: Version 5.9.3
Node.js version: v22.21.0
OS: Documentation generated on desktop - macos 15.7.2
Bug reproduced on real iOS device (Safari and Chrome): iOs 26.1

[alguiguilo098]

Hi! @Gerrit0 👋
I’ve read through the issue description and understand the problem.
I’d like to work on it and contribute a fix.
May I take this issue?
Thanks!

[Gerrit0]

No need to ask for permission, go for it!