Overview

The router provides four functions for programmatic navigation: push(), replace(), pop(), and goBack(). The push() and replace() functions support multiple convenient input formats.

Navigation Functions

push()

Purpose: Navigate to a new page

Behavior: Adds new entry to history stack

User can: Use back button to return

push() example 
 
 
replace()
 
Purpose: Replace current page
 
Behavior: Replaces current history entry
 
User can: NOT use back button to return to replaced page
 
replace() example 
 
 
 
pop()
 
Purpose: Go back in history
 
Behavior: Equivalent to browser back button
 
User sees: Previous page from history
 
pop() example 
 
 
 
Link Format Examples
 
Both push() and replace() support seven flexible input formats.
				Here are code examples for each format:
 
Format 1: Simple String Path
 
Use a plain string for direct navigation to static routes:
 
Format 1: String path 
 
 
 
Format 2: Array with Route Name Only
 
Use an array with just the route name (requires named routes setup):
 
Format 2: Array [routeName] 
 
 
 
Format 3: Array with Route Name and Parameters
 
Use an array with route name and parameters object:
 
Format 3: Array [routeName, params] 
 
 
 
Format 4: Array with Route Name, Parameters, and Query
 
Use an array with route name, parameters, and query string object:
 
Format 4: Array [routeName, params, query] 
 
 
 
Format 5: Object with Route Name Only
 
Use an object with just the route property:
 
Format 5: Object { route } 
 
 
 
Format 6: Object with Route Name and Parameters
 
Use an object with route and params properties:
 
Format 6: Object { route, params } 
 
 
 
Format 7: Object with All Options
 
Use an object with route, params, and query properties for complete control:
 
Format 7: Object { route, params, query } 
 
 
 
Format Comparison
 
Here's the same navigation using all three formats:
 
Same navigation, three ways 
 
 
 
Which format should I use?
 
  • String format: Best for simple, static routes
    •  
  • Array format: Recommended for named routes - concise and readable
    •  
  • Object format: Best for complex navigation with many parameters, or when you want maximum clarity
 
Practical Examples
 
Form Submission
 
Navigate after form submission 
 
 
 
Login Redirect
 
Replace after login 
 
 
 
Pagination
 
Pagination navigation 
 
 
 
Conditional Navigation
 
Conditional navigation 
 
 
 
Back Navigation
 
Smart back navigation 
 
 
 
Common Patterns
 
Navigation after API call
 
Navigate after API call 
 
 
 
Navigate with preserved filters
 
Preserve query parameters 
 
 
 
Multi-step wizard
 
Wizard navigation 
 
 
 
Best Practices
 
✅ Do
 
  • Use replace() for login/logout flows to prevent back button issues
    •  
  • Use named routes with registerRoutes() for maintainability
    •  
  • Use await with navigation functions to handle completion
    •  
  • Preserve query parameters when navigating between related views
    •  
  • Use pop() instead of hardcoding back navigation
 
⚠️ Don't
 
  • Don't call navigation functions in a tight loop
    •  
  • Don't forget to handle navigation errors in try/catch
    •  
  • Don't hardcode URLs - use named routes instead
    •  
  • Don't use push() for redirects after form submission - consider replace()
 
TypeScript Support
 
All navigation functions are fully typed with TypeScript:
 
TypeScript support 
 
 
 
Try It Live
 
See programmatic navigation in action in the example application at /links-demo. The demo includes interactive buttons to test all three formats.
 
Example App: Check out example-history/src/routes/LinksDemo.svelte for a complete working example
					with all navigation formats.