{"record":{"id":"34ab32242a1c05d7","repo":"sveltejs/kit","slug":"can-only-disable-scroll-handling-during-navigation","errorCode":null,"errorMessage":"Can only disable scroll handling during navigation","messagePattern":"Can only disable scroll handling during navigation","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/kit/src/runtime/client/client.js","lineNumber":2622,"sourceCode":" *\n * If a function (or a `Promise` that resolves to a function) is returned from the callback, it will be called once the DOM has updated.\n *\n * `onNavigate` must be called during a component initialization. It remains active as long as the component is mounted.\n * @param {(navigation: OnNavigate) => import('types').MaybePromise<(() => void) | void>} callback\n * @returns {void}\n */\nexport function onNavigate(callback) {\n\tadd_navigation_callback(on_navigate_callbacks, callback);\n}\n\n/**\n * If called when the page is being updated following a navigation (in `onMount` or `afterNavigate` or an action, for example), this disables SvelteKit's built-in scroll handling.\n * This is generally discouraged, since it breaks user expectations.\n * @returns {void}\n */\nexport function disableScrollHandling() {\n\tif (DEV && started && !updating) {\n\t\tthrow new Error('Can only disable scroll handling during navigation');\n\t}\n\n\tif (updating || !started) {\n\t\tautoscroll = false;\n\t}\n}\n\nlet warned_on_invalidate_all = false;\nlet warned_on_replace_state = false;\nlet warned_on_push_state = false;\nlet warned_on_replace_state_function = false;\n\n/**\n * @param {string | URL} url\n * @param {'goto' | 'pushState' | 'replaceState'} caller\n */\nasync function resolve_intent(url, caller) {\n\tconst resolved = new URL(resolve_url(url));","sourceCodeStart":2604,"sourceCodeEnd":2640,"githubUrl":"https://github.com/sveltejs/kit/blob/03f1687fe612ce3d2d9131139b5b188d9cf90c64/packages/kit/src/runtime/client/client.js#L2604-L2640","documentation":"`disableScrollHandling()` only works synchronously during a client-side navigation update (i.e. from `load`, `onMount` during navigation, `afterNavigate`, or an action while navigation is in progress). In DEV, calling it outside that window throws, because there is no in-flight navigation whose scroll behavior can be changed.","triggerScenarios":"Calling `disableScrollHandling()` in a `setTimeout`/`await`-deferred callback, in an event handler, in `afterNavigate` after the update finished, or on first page load after hydration (`started && !updating`).","commonSituations":"Calling it after awaiting data in `load`; calling from a click handler to stop scroll jumps; calling in `afterNavigate` when the navigation already completed.","solutions":["Call `disableScrollHandling()` synchronously at the top of a `load` function (non-deferred)","Alternatively use `<a data-sveltekit-noscroll>` on the link instead of calling the function","If you need post-navigation control, use `goto(url, { noScroll: true })` or `invalidate(..., { noScroll })` style options rather than the function after the fact"],"exampleFix":"// before\nexport const load = async ({ fetch }) => {\n  const data = await fetch('/api').then((r) => r.json());\n  disableScrollHandling();\n  return data;\n};\n// after\nexport const load = () => {\n  disableScrollHandling();\n  return { }; // sync call before any await/defer\n};","handlingStrategy":"validation","validationCode":"import { dev } from '$app/environment';\nfunction safeDisableScrollHandling(disableScrollHandling, updating, started) {\n  if (dev && started && updating) disableScrollHandling();\n  else console.warn('disableScrollHandling ignored outside navigation');\n}","typeGuard":"const canDisableScroll = (started, updating) => started && updating;","tryCatchPattern":"try {\n  disableScrollHandling();\n} catch (e) {\n  if (e.message.includes('during navigation')) {\n    // use data-sveltekit-noscroll or goto(url, { noScroll: true }) instead\n  } else throw e;\n}","preventionTips":["Call disableScrollHandling synchronously at the top of load, never after await","Prefer declarative `data-sveltekit-noscroll` links or `goto` noScroll options","Add a code comment/lint reminder that the API is navigation-scoped"],"tags":["navigation","scroll","dev-guard"],"backgroundTag":"scroll-handling-outside-navigation","analyzedSha":"03f1687fe612ce3d2d9131139b5b188d9cf90c64","analyzedAt":"2026-09-02T02:01:50.504Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}