fix: scroll to anchor on Safari after Next.js hydration

Safari does not re-scroll to hash targets after client-side hydration
replaces the server-rendered DOM. This causes anchored links like
`/concepts/tools#typed-tool-outputs` to load at the top of the page
instead of scrolling to the target section.

This custom script retries scrolling to the hash target after page load,
waiting for React hydration to settle. Mintlify auto-includes any .js
file in the docs directory on every page.

Tested with: Safari 18 on macOS
This commit is contained in:
Iris Clawd
2026-06-19 22:42:44 +00:00
parent 9db2d44766
commit 6f5c99ed36

43
docs/safari-anchor-fix.js Normal file
View File

@@ -0,0 +1,43 @@
/**
* Fix for anchor/hash links not scrolling on Safari.
*
* Safari does not re-scroll to the hash target after Next.js hydration
* replaces the server-rendered DOM. This script watches for the target
* element and scrolls to it once it appears.
*/
(function () {
if (typeof window === 'undefined') return;
function scrollToHash() {
var hash = window.location.hash;
if (!hash) return;
var id = hash.substring(1);
var el = document.getElementById(id);
if (el) {
el.scrollIntoView();
return true;
}
return false;
}
// Try immediately (works in Chrome/Firefox).
if (scrollToHash()) return;
// For Safari: retry after hydration settles.
// Use requestAnimationFrame + small delay to wait for React hydration.
var attempts = 0;
var maxAttempts = 20; // ~2 seconds max
function retry() {
attempts++;
if (scrollToHash() || attempts >= maxAttempts) return;
setTimeout(retry, 100);
}
if (document.readyState === 'complete') {
retry();
} else {
window.addEventListener('load', retry);
}
})();