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 navigate function lets you trigger route changes from JavaScript code — no <Link> component required. It is the go-to tool for redirecting users after form submissions, async operations such as authentication flows, or any logic-driven navigation that cannot be expressed declaratively. Under the hood, navigate is re-exported directly from the globalHistory singleton created by createHistory, so every call shares the same browser history session.

​
Import

import { navigate } from 'svelte5-router';

​
Signature

navigate(
  to: string,
  options?: {
    replace?: boolean;
    state?: Record<string | number, unknown>;
    preserveScroll?: boolean;
    blurActiveElement?: boolean;
  }
): void

​
Parameters

​
to
string
required
The destination path to navigate to, e.g. "/dashboard" or "/blog/42?tab=comments". Must be a same-origin path; the function calls history.pushState or history.replaceState internally.
​
options.replace
boolean
default:"false"
When true, the current history entry is replaced instead of a new entry being pushed. The user will not be able to press the browser back button to return to the page that called navigate. Useful for login redirects and post-submit flows where going back would re-trigger the action.
​
options.state
Record<string | number, unknown>
default:"{}"
An arbitrary serialisable object stored alongside the history entry via the Web History API. Accessible through window.history.state or the useHistory / useLocation hooks. A key property (timestamp string) is merged in automatically by the router.
​
options.preserveScroll
boolean
default:"false"
When true, the page will not scroll to the top after navigation. Useful for list→detail transitions where preserving scroll position improves UX.
​
options.blurActiveElement
boolean
default:"false"
When true, document.activeElement.blur() is called after navigation. Helpful for keyboard-driven UIs where focus should return to the document body after a navigation action.

​
Return value

​
void
navigate returns nothing. Side effects are the history entry change and notifications to all registered listeners.

​
How it works

navigate is the navigate method of globalHistory, a createHistory instance that wraps window.history (or a memory-based fallback in SSR / non-DOM environments). When called, it:
  1. Merges a timestamped key into state.
  2. Calls window.history.pushState or window.history.replaceState depending on replace.
  3. Updates the internal location snapshot.
  4. Notifies every registered listener with { location, action: "PUSH", preserveScroll }.
  5. Optionally blurs the active element.
iOS Safari pushState limit — Safari on iOS caps pushState calls at 100 per 30-second window. svelte5-router catches the resulting SecurityError and falls back to location.assign(to) (or location.replace(to) when replace is true), which causes a full-page navigation but keeps the app functional.

​
push vs. replace

Scenarioreplace valueEffect
Normal link clickfalse (default)New entry added; back button returns to previous page
Post-login redirecttrueCurrent entry replaced; back button skips the login page
Wizard step navigationfalseEach step is a history entry; back/forward works step-by-step
Error redirecttrueAvoids an unreachable “error” URL in history

​
Examples

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

  async function onSubmit() {
    await login();
    // Replace the login page in history so the user can't
    // accidentally navigate back to the login form.
    navigate('/success', { replace: true });
  }
</script>

<form onsubmit={(e) => { e.preventDefault(); onSubmit(); }}>
  <!-- form fields -->
  <button type="submit">Log in</button>
</form>
Inside Svelte components, you can also retrieve the navigate function from the useHistory hook to stay within Svelte’s reactive context:
<script lang="ts">
  import { useHistory } from 'svelte5-router';
  const { navigate } = useHistory();
</script>
Outside components (e.g. in plain TypeScript modules or service files), import navigate directly from svelte5-router.

Build docs developers (and LLMs) love

Get started for freeTalk to us