Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jpcutshall/svelte5-router/llms.txt

Use this file to discover all available pages before exploring further.

The listen function lets you register a callback that fires whenever the current route changes, whether that change came from a navigate() call, a <Link> click, or the browser’s back/forward buttons. It is designed for use outside of Svelte components — for example in plain TypeScript modules, analytics helpers, or application bootstrap code. Inside Svelte components you should prefer the useLocation, useRouter, or useHistory hooks, which integrate cleanly with Svelte’s reactivity system and automatically clean up when the component is destroyed.

​
Import

import { listen } from 'svelte5-router';

​
Signature

listen(
  fn: (event: {
    location: Location & { state: any; key: string };
    action: 'POP' | 'PUSH';
    preserveScroll?: boolean;
  }) => void
): () => void

​
Parameters

​
fn
function
required
A callback invoked on every route change. Receives a single event object with three properties:
  • location — A snapshot of the current window.location extended with state (from window.history.state) and key (a timestamp string). Includes the standard pathname, search, hash, href, and origin properties.
  • action — Either "PUSH" (navigate/Link triggered) or "POP" (browser back/forward button). See action values below.
  • preserveScroll — Forwarded from the originating navigate() call. undefined on "POP" actions.

​
Return value

​
unsubscribe
() => void
A zero-argument function that removes the listener and cleans up the underlying popstate event handler. Always call this when the listener is no longer needed to prevent memory leaks.

​
Action values

ValueTriggered byNotes
"PUSH"navigate(), <Link> clicks, use:link, use:linksA new entry was added to (or replaced in) the history stack
"POP"Browser back / forward buttons, history.go()The user moved within the existing history stack
"PUSH" is emitted for both pushState and replaceState operations. There is no separate "REPLACE" action — if you need to distinguish them, check whether the location.key has changed between events.

​
Examples

import { listen as addListener } from 'svelte5-router';

function init() {
  addListener(({ location }) => {
    console.log(location.pathname);
  });
}

​
Inside vs. outside components

ContextRecommended APIReason
Outside Svelte componentslisten()No Svelte context available; manage lifecycle manually
Inside Svelte componentsuseLocation(), useRouter(), useHistory()Hooks integrate with Svelte’s $state / $derived reactivity and auto-cleanup on destroy
If you call listen inside a Svelte component without calling the returned unsubscribe function in onDestroy, the listener will survive the component’s destruction and accumulate on every remount. Use useLocation inside components instead.
The listen export is the listen method of the shared globalHistory singleton. Every listener registered through it hears the same events, regardless of how many <Router> instances are active.

Build docs developers (and LLMs) love

Get started for freeTalk to us