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.

useHistory() returns the history object that the nearest ancestor <Router> is using to track and drive navigation. By default this is svelte5-router’s built-in globalHistory, which wraps the browser’s window.history API (or a memory-based fallback during SSR). If a <Router> was given a custom history prop, useHistory() returns that custom instance instead—making it the correct way to perform imperative navigation inside a component when you need to respect a potentially overridden history. Like the other context hooks, it must be called during Svelte component initialisation.

​
Signature

import { useHistory } from "svelte5-router";

const history = useHistory();
// history is HistoryContext (the same shape as globalHistory)

​
Return value

useHistory() returns a HistoryContext object with the following shape.

​
HistoryContext

​
location
Location & { state: any; key: string }
required
A read-only snapshot of the current location. This is a plain object—not a store—so it reflects the location at the moment of access. For a reactive store that updates on every navigation, use useLocation() instead.
​
listen
(listener: Listener) => () => void
required
Subscribes to location changes. The listener is called whenever a navigation occurs, whether triggered by navigate(), a <Link> click, or the browser’s back/forward buttons.Returns an unsubscribe function—call it to remove the listener and prevent memory leaks.
​
navigate
(to: string, options?: NavigateOptions) => void
required
Imperatively navigates to the given path. Notifies all registered listeners after the navigation.
​
to
string
required
The destination path to navigate to, e.g. "/dashboard" or "/search?q=svelte".
​
options
NavigateOptions
Optional configuration for the navigation.

​
useHistory() vs. top-level navigate()

The top-level navigate() export always uses globalHistory—the default browser history singleton. useHistory() returns whichever history object was passed to the nearest <Router> via its history prop.
navigate() (top-level)history.navigate() from useHistory()
Usable outside components✅ Yes❌ No (requires context)
Respects custom history prop❌ No✅ Yes
Good for SSR / testing❌ No (uses window)✅ Yes (if a memory history is injected)
// Top-level — always uses the global browser history
import { navigate } from "svelte5-router";
navigate("/dashboard");

<script lang="ts">
  // Inside a component — uses the Router's history, which may be custom
  import { useHistory } from "svelte5-router";

  const history = useHistory();
  // history.navigate respects any custom history passed to <Router history={...}>
</script>

​
Examples

​
Imperative navigation after a form submission

The most common use case for useHistory() is redirecting programmatically after an async operation such as a form submission or authentication flow. 
<script lang="ts">
  import { useHistory } from "svelte5-router";

  const history = useHistory();

  let email = $state("");
  let password = $state("");
  let error = $state<string | null>(null);

  async function handleSubmit(e: SubmitEvent) {
    e.preventDefault();
    error = null;
    try {
      await login(email, password);
      history.navigate("/dashboard", {
        replace: true,
        state: { from: "login" },
      });
    } catch (err) {
      error = (err as Error).message;
    }
  }
</script>

<form onsubmit={handleSubmit}>
  <label>
    Email
    <input type="email" bind:value={email} />
  </label>
  <label>
    Password
    <input type="password" bind:value={password} />
  </label>
  {#if error}
    <p class="error">{error}</p>
  {/if}
  <button type="submit">Log in</button>
</form>

​
Listening to navigation events from within a component

<script lang="ts">
  import { onDestroy } from "svelte";
  import { useHistory } from "svelte5-router";

  const history = useHistory();

  // listen() returns an unsubscribe function — clean up on component destroy
  const unlisten = history.listen(({ location, action }) => {
    console.log(`[${action}] navigated to ${location.pathname}`);
  });

  onDestroy(unlisten);
</script>
Always store the return value of history.listen() and call it inside onDestroy to avoid memory leaks when the component is unmounted.
<script lang="ts">
  import { useHistory } from "svelte5-router";

  const history = useHistory();

  function loadNextPage(page: number) {
    history.navigate(`/results?page=${page}`, { preserveScroll: true });
  }
</script>

<button onclick={() => loadNextPage(3)}>Page 3</button>

​
Complete form component example

<script lang="ts">
  import { useHistory } from "svelte5-router";

  const history = useHistory();

  let name = $state("");
  let email = $state("");
  let submitting = $state(false);
  let serverError = $state<string | null>(null);

  async function register(e: SubmitEvent) {
    e.preventDefault();
    submitting = true;
    serverError = null;

    try {
      await api.register({ name, email });

      // Replace so the back button skips the form
      history.navigate("/welcome", {
        replace: true,
        state: { registeredEmail: email },
        blurActiveElement: true,
      });
    } catch (err) {
      serverError = (err as Error).message;
    } finally {
      submitting = false;
    }
  }
</script>

<form onsubmit={register}>
  <label>
    Name
    <input type="text" bind:value={name} required />
  </label>
  <label>
    Email
    <input type="email" bind:value={email} required />
  </label>

  {#if serverError}
    <p role="alert" class="error">{serverError}</p>
  {/if}

  <button type="submit" disabled={submitting}>
    {submitting ? "Registering…" : "Create account"}
  </button>
</form>

​
Constraints

useHistory() uses Svelte’s getContext() and must be called during component initialisation, at the top level of a <script> block inside a .svelte file. It cannot be used in plain .ts files or inside callbacks and effects.
For navigation outside Svelte components—such as in utility modules or service files—use the top-level navigate() export instead.
import { navigate } from "svelte5-router";
navigate("/login");

Build docs developers (and LLMs) love

Get started for freeTalk to us