feat: scroll behavior (#50)

Author: colinlienard

.changeset/empty-donkeys-notice.md

@@ -0,0 +1,5 @@
+---
+'sv-router': patch
+---
+
+Scroll behavior features

docs/.vitepress/config.ts

@@ -57,6 +57,7 @@ export default defineConfig({
 						{ text: 'Search Params', link: '/guide/common/search-params' },
 						{ text: 'Active Route', link: '/guide/common/active-route' },
 						{ text: 'Preloading', link: '/guide/common/preloading' },
+						{ text: 'Scroll Behavior', link: '/guide/common/scroll-behavior' },
 					],
 				},
 				{

docs/guide/common/scroll-behavior.md

@@ -0,0 +1,41 @@
+# Scroll Behavior
+
+## Scroll To Top
+
+By default, the router automatically scrolls to the top of the page when navigating to a new route. You can customize this behavior on a per-navigation basis by providing a `scrollToTop` option:
+
+```ts
+// Default behavior - scroll to top instantly
+navigate('/about');
+
+// Scroll to top with smooth animation
+navigate('/about', { scrollToTop: 'smooth' });
+
+// Prevent scrolling to top
+navigate('/about', { scrollToTop: false });
+```
+
+This property accepts the same values as the `behavior` parameter of the browser's [`scrollTo` method](https://developer.mozilla.org/en-US/docs/Web/API/Window/scrollTo#parameters).
+
+For standard anchor tags, control scroll behavior with the `data-scroll-to-top` attribute:
+
+```svelte
+<!-- Default behavior - scroll to top instantly -->
+<a href={p('/about')}>About</a>
+
+<!-- Scroll to top with smooth animation -->
+<a href={p('/about')} data-scroll-to-top="smooth">About</a>
+
+<!-- Prevent scrolling to top -->
+<a href={p('/about')} data-scroll-to-top="false">About</a>
+```
+
+## Scroll Position Restoration
+
+sv-router leverages the browser's native scroll restoration mechanism by default. This means that when using the browser back/forward buttons, scroll positions are automatically restored.
+
+If you want to implement your own scroll restoration logic or disable it entirely, you can opt-out of the browser's native behavior through the [`scrollRestoration` property of the History API](https://developer.mozilla.org/en-US/docs/Web/API/History/scrollRestoration):
+
+```ts
+history.scrollRestoration = 'manual';
+```

docs/reference/index.md

@@ -46,6 +46,7 @@ Programmatically navigate to a route.
   - `search` - Query string
   - `state` - History state to save
   - `hash` - URL hash fragment
+  - `scrollToTop` - Scroll behavior (`"auto" | "instant" | "smooth" | false`)
   - `params` - Parameters to substitute in the path
 
 #### `isActive(path, params?)`

src/create-router.svelte.js

@@ -113,6 +113,10 @@ export async function onNavigate(path, options = {}) {
 	syncSearchParams();
 	Object.assign(location, updatedLocation());
 
+	if (options.scrollToTop !== false) {
+		window.scrollTo({ top: 0, left: 0, behavior: options.scrollToTop });
+	}
+
 	for (const { afterLoad } of hooks) {
 		afterLoad?.();
 	}
@@ -130,12 +134,13 @@ export function onGlobalClick(event) {
 	if (url.origin !== currentOrigin) return;
 
 	event.preventDefault();
-	const { replace, state } = anchor.dataset;
+	const { replace, state, scrollToTop } = anchor.dataset;
 	onNavigate(url.pathname, {
 		replace: replace === '' || replace === 'true',
 		search: url.search,
 		state,
 		hash: url.hash,
+		scrollToTop: scrollToTop === 'false' ? false : /** @type ScrollBehavior */ (scrollToTop),
 	});
 }
 

src/index.d.ts

@@ -162,6 +162,7 @@ export type NavigateOptions =
 			search?: string;
 			state?: string;
 			hash?: string;
+			scrollToTop?: ScrollBehavior | false;
 	  }
 	| undefined;