The router provides extensive callback and event mechanisms to hook into the routing lifecycle, implement custom logic, and respond to navigation events.

Callbacks vs Events:
  • Events are fired by the Router component (onrouteLoading, onrouteLoaded, etc.) to notify your app of routing state changes
  • Callbacks are functions you provide (conditions, authorizationCallback, etc.) that the router calls to make decisions

Router Component Events

These event handler props are passed to the <Router> component and fire at specific points in the routing lifecycle.

onRouteLoading

Fires when a route starts loading, after route match but before conditions are checked and the component is loaded.

Event Detail Structure

Event Detail 
 
 
Usage Example
 
Basic Usage 
 
 
 
Use Case: Show loading indicators, start performance timers, prepare
						UI state
 
onRouteLoaded
 
Fires after a route successfully loads and all conditions pass. Called for both
						single-component and zone-based routes.
 
Event Detail Structure (Single Component)
 
Event Detail 
 
 
 
Event Detail Structure (Zone-Based Routes)
 
Zone-Based Event Detail 
 
 
 
Usage Example
 
Analytics Integration 
 
 
 
Use Case: Hide loading spinners, send analytics events, update page
						title, measure performance
 
onConditionsFailed
 
Fires when route conditions (guards) fail, preventing navigation to the requested
						route.
 
Event Detail Structure
 
Event Detail 
 
 
 
Usage Example
 
Redirect on Failure 
 
 
 
Use Case: Redirect to login/unauthorized pages, show error messages,
						log security events
 
onNotFound
 
Fires when no route matches the current location (404 error).
 
Event Detail Structure
 
Event Detail 
 
 
 
Usage Example
 
Error Tracking 
 
 
 
Use Case: Send to Sentry/error tracking, analytics, log broken links
 
Navigation Guard Callbacks
 
Navigation guards allow you to prevent users from leaving a route when there are unsaved
				changes or other conditions.
 
registerBeforeLeave
 
Register a callback that runs before navigating away from the current route. Throw NavigationCancelledError to prevent navigation.
 
Callback Signature
 
Function Signature 
 
 
 
Usage Example
 
Prevent Navigation with Unsaved Changes 
 
 
 
Tip: Use the createDirtyCheckGuard helper for simpler
						dirty state checking:
 
Using Helper 
 
 
 
Route Condition Callbacks
 
Conditions are async functions that run before a route's component loads. Return false to block navigation.
 
conditions Array
 
Pass an array of condition functions to wrap(). Each function receives
						route details and must return a boolean.
 
Callback Signature
 
Function Signature 
 
 
 
Usage Example
 
Multiple Conditions 
 
 
 
Execution Order: In hierarchical mode, parent route conditions run before child route conditions. All conditions must pass for navigation to succeed.
 
Permission System Callbacks
 
The permission system requires configuration callbacks to check user permissions and handle
				unauthorized access.
 
configurePermissions
 
Configure the permission system with three required callbacks:
 
checkPermissions
 
Function Signature 
 
 
 
getCurrentUser
 
Function Signature 
 
 
 
onUnauthorized
 
Function Signature 
 
 
 
Complete Configuration Example
 
Full Configuration 
 
 
 
authorizationCallback
 
Resource-based authorization callback for checking access to specific resources
						(e.g., documents, projects).
 
Callback Signature
 
Function Signature 
 
 
 
Usage Example
 
Resource Authorization 
 
 
 
Performance Tip: Permission checks run before authorization
						callbacks to avoid unnecessary API calls. In hierarchical mode, parent authorization runs
						before child authorization.
 
Error Handler Callbacks
 
The global error handler provides callbacks for logging errors and implementing custom
				recovery strategies.
 
onError
 
Called whenever an unhandled error occurs. Use this to send errors to monitoring
						services like Sentry.
 
Callback Signature
 
Function Signature 
 
 
 
Usage Example
 
Error Logging 
 
 
 
onRecover
 
Called when using strategy: 'custom' to implement custom error recovery
						logic.
 
Callback Signature
 
Function Signature 
 
 
 
Usage Example
 
Custom Recovery Strategy 
 
 
 
Built-in Strategies: 
  • 'navigateSafe' - Navigate to safe route (default)
    •  
  • 'restart' - Reload the page (with loop prevention)
    •  
  • 'showError' - Display error component
    •  
  • 'custom' - Call onRecover callback
 
Lifecycle & Execution Order
 
Understanding the order in which callbacks execute is crucial for proper routing logic.
 
Navigation Lifecycle
 
When navigating to a new route, callbacks execute in this order:
 
  1. registerBeforeLeave handlers (if leaving a route) 
    • All registered handlers execute
      •  
    • Navigation cancelled if any throws NavigationCancelledError
    2.  
  2. onrouteLoading event fires 
    • Route matched but not yet loaded
    3.  
  3. Route matching 
    • Pattern matching against current location
      •  
    • Parameter extraction
    4.  
  4. conditions array execution 
    • In hierarchical mode: parent conditions execute first
      •  
    • All conditions must return true to proceed
    5.  
  5. checkPermissions (if using permission system) 
    • Fast role-based check
      •  
    • In hierarchical mode: parent permissions checked first
    6.  
  6. authorizationCallback (if defined) 
    • Slow resource-based check (API calls)
      •  
    • Only runs if permissions pass
      •  
    • In hierarchical mode: parent authorization runs first
    7.  
  7. Component loading 
    • Async component import resolves
      •  
    • Component instantiated
    8.  
  8. onrouteLoaded event fires (success path) 
    • Route fully loaded and rendered
 
Alternative Paths: 
  • If no route matches → onNotFound fires
    •  
  • If conditions/permissions fail → onconditionsFailed fires
    •  
  • If unhandled error occurs → onError callback (if configured)
 
Hierarchical Mode Execution
 
When hierarchical routes are enabled, parent callbacks execute before child callbacks:
 
Hierarchical Execution 
 
 
 
This matches filesystem security where you need access to all parent directories to
						reach a nested file.
 
Quick Reference
 
Summary of all callbacks and events with their primary use cases.
 
Callback/EventTypeWhen CalledPrimary Use Case
onRouteLoadingEventRoute starts loadingShow loading indicator, start timer
onRouteLoadedEventRoute successfully loadsAnalytics, hide loading, log page view
onConditionsFailedEventRoute conditions failRedirect to unauthorized page
onNotFoundEventNo route matches (404)Error tracking, analytics, logging
registerBeforeLeaveCallbackUser tries to leave routePrevent navigation with unsaved changes
conditionsCallbackBefore component loadsAuthentication, feature flags
checkPermissionsCallbackPermission check neededRole-based access control
getCurrentUserCallbackUser info neededGet current user object
onUnauthorizedCallbackPermission deniedRedirect to login/unauthorized
authorizationCallbackCallbackResource access checkAPI-based authorization
onErrorCallbackUnhandled error occursSend to Sentry, log to service
onRecoverCallbackCustom recovery strategyCustom error recovery logic
 
Related Documentation
 
Guards & Conditions
 
Learn more about implementing route guards and navigation protection.
 View Guards Guide
 
Permissions System
 
Detailed guide to role-based and resource-based access control.
 View Permissions Guide