Svelte SPA Router

🧭 Navigation Functions

Programmatic navigation between routes

Function Reference

Function	Parameters	Returns	Description
`push()`	`location: string \| array \| object` `param2?: any` `param3?: Record<string, any>` `param4?: any`	`Promise<void>`	Navigate to new route, adding to browser history
`replace()`	`location: string \| array \| object` `param2?: any` `param3?: Record<string, any>` `param4?: any`	`Promise<void>`	Replace current route without adding to history
`pop()`	-	`Promise<void>`	Navigate back in history (browser back button)
`goBack()`	-	`Promise<void>`	Navigate to referrer with automatic scroll restoration

Usage Examples

Navigation Functions

Navigation Details

📍 Multiple Formats

All navigation functions support multiple calling formats: string, array, object, and multi-parameter.

🔄 History Management

push(): Adds to browser history (user can go back)
replace(): Replaces current entry (no back navigation)
pop(): Browser back button equivalent
goBack(): Navigate to referrer with automatic scroll restoration (requires referrer tracking enabled)

🎯 Navigation Context

Pass data between routes without showing it in URL using the navigationContext parameter.

📊 State Accessor Functions

Access current routing state

Function Reference

Function	Returns	Description
`location()`	`string`	Get current location path (e.g., `'/about'`)
`querystring()`	`string`	Get raw query string without '?' (e.g., `'foo=bar'`)
`query() query<T>()`	`Record<string, string \| string[]> T`	Get parsed querystring as object. Optional generic type for intellisense
`routeParams() routeParams<T>()`	`Record<string, string> \| undefined T \| undefined`	Get current route parameters from URL pattern. Optional generic type for intellisense
`navigationContext() navigationContext<T>()`	`any \| null T \| null`	Get navigation context data passed during navigation. Optional generic type for intellisense
`loc()`	`Location`	Get full location object with path and querystring

Usage Examples

State Accessors

State Details

⚡ Reactive State

All accessor functions return current values and work with Svelte's $derived for reactivity.

🔤 TypeScript Support

Use generic type parameters for type-safe route parameters and navigation context.

📦 Location Object

The loc() function returns both location and querystring in one call.

⚙️ Configuration Functions

Configure router behavior (must be called before app mount)

Function Reference

Function	Parameters	Description
`setHashRoutingEnabled()`	`value: boolean`	Enable hash mode (true) or history mode (false). Default: true
`setBasePath()`	`value: string`	Set base path for history mode (e.g., `'/app'`)
`setParamReplacementPlaceholder()`	`value: string`	Set placeholder for missing route parameters. Default: 'N-A'
`getHashRoutingEnabled()`	-	Get current routing mode (hash or history)
`getBasePath()`	-	Get current base path setting
`getParamReplacementPlaceholder()`	-	Get current parameter placeholder value

Usage Examples

Router Configuration

Configuration Details

🔀 Routing Modes

Hash mode: URLs like #/about (default, no server config needed)
History mode: Clean URLs like /about (requires server fallback)

📍 Base Path

Use when app is hosted in a subdirectory (e.g., example.com/my-app/about).

⚠️ Timing

All configuration functions must be called before mounting your Svelte app.

📦 Route Wrapping

Wrap routes with async loading, conditions, and metadata

Function Reference

Function	Parameters	Description
`wrap()`	`options: WrapOptions`	Wrap component with async loading, conditions, props, and loading state

WrapOptions Interface

Property	Type	Description
`component`	`Component \| AsyncComponent`	Svelte component or async loader function
`conditions`	`Function[]`	Route guard conditions (must all return true)
`props`	`Record<string, any>`	Static props to pass to component
`routeContext`	`any`	Custom metadata for the route
`loadingComponent`	`Component`	Component to show while loading async route
`shouldDisplayLoadingOnRouteLoad`	`boolean`	Wait for component data before hiding loading

Usage Examples

Route Wrapping

Wrapping Details

🔄 Async Loading

Use dynamic imports for code splitting. Show loading component while route loads.

🛡️ Route Guards

Add conditions that must pass before showing route. Perfect for authentication checks.

📊 Route Metadata

Attach custom data like breadcrumbs, page titles, or permissions to routes.

🏷️ Named Routes

Function Reference

Function	Parameters	Description
`registerRoutes()`	`routes: Record<string, string>`	Register named routes for navigation
`getRegisteredRoutes()`	-	Get all registered named routes
`resolveNamedRoute()`	`name: string` `params?: Record<string, any>`	Resolve named route to path with parameters

Usage Examples

Named Routes

Named Routes Details

📛 Why Named Routes?

Change URL patterns without updating navigation calls throughout your app.

🔗 Type Safety

Centralize route definitions for easier refactoring and TypeScript support.

⚡ Dynamic Resolution

Build URLs with parameters at runtime using resolveNamedRoute().

🔐 Permissions & Authorization

Role-based and resource-based access control

Function Reference

Function	Parameters	Description
`configurePermissions()`	`config: PermissionConfig`	Configure permission system with user permissions provider
`hasPermission()`	`permission: string \| string[]`	Check if user has specific permission(s)
`createProtectedRoute()`	`options: ProtectedRouteOptions`	Create route with permission and authorization checks
`createProtectedRouteDefinition()`	`options: ProtectedRouteOptions`	Create protected route definition for use with wrap()

Usage Examples

Permissions

Permission Details

🛡️ Two-Layer Security

Role-based: Fast permission checks (any/all)
Resource-based: Slow API calls for specific resources

⚡ Performance

Permissions checked first (fast), then authorizationCallback (slow API call) only if needed.

🎯 Flexible Checks

Use any: [] for OR logic or all: [] for AND logic in permission requirements.

🎬 Svelte Actions

Declarative routing and active link highlighting

Action Reference

Action	Parameters	Description
`use:link`	`href?: string \| array \| LinkActionOptions`	Enable SPA navigation on anchor tags
`use:active`	`className?: string`	Add CSS class to active links. Default: 'active'

Usage Examples

Svelte Actions

Action Details

🔗 Link Action

Prevents full page reload, enables SPA navigation. Works with modifier keys (Ctrl+Click) in history mode.

✨ Active Action

Automatically adds CSS class when link matches current route. Perfect for nav menus.

🎨 Styling

Customize the active class name to match your CSS framework or design system.

🧩 Components

Main router and error handling components

Component Reference

Component	Props
`<Router>`	`routes*: RoutesMap` `prefix?: string` `zone?: string` `restoreScrollState?: boolean` `onrouteEvent?: Function` `onRouteLoading?: Function` `onRouteLoaded?: Function` `onConditionsFailed?: Function` `onNotFound?: Function`
`<GlobalErrorHandler>`	No props - configure via `configureGlobalErrorHandler()`

* Required props

Usage Examples

Components

Component Details

🎯 Router Component

Main component that renders the current route. Supports nested routers via prefix and multi-zone routing via zone.

🚨 Error Handler

Catches all unhandled errors. Configure recovery strategies with configureGlobalErrorHandler().

📜 Scroll Restoration

Enable restoreScrollState to save/restore scroll positions on navigation.