Router Events

TanStack Router exposes router lifecycle events through router.subscribe. This is useful for imperative side effects like analytics, resetting external state, or running DOM-dependent logic after navigation.

router.subscribe takes an event name and a listener, then returns an unsubscribe function:

const unsubscribe = router.subscribe('onResolved', (event) => {
  console.info('Navigation finished:', event.toLocation.href)
})

// Later, clean up the listener
unsubscribe()

const unsubscribe = router.subscribe('onResolved', (event) => {
  console.info('Navigation finished:', event.toLocation.href)
})

// Later, clean up the listener
unsubscribe()

router.subscribe is best for imperative integrations that need to observe navigation without driving rendering:

• Analytics and pageview tracking
• Resetting external caches or mutation state
• Logging navigation timing and transitions
• Running DOM-dependent logic after routes render

If you need reactive UI updates, prefer framework hooks like useRouterState, useSearch, and useParams instead of subscribing manually.

TanStack Router emits these lifecycle events:

• onBeforeNavigate - right before a navigation begins
• onBeforeLoad - before route loading starts
• onLoad - after the next location has committed and route matches have loaded
• onBeforeRouteMount - after loading finishes, just before route components mount
• onResolved - after the navigation has fully resolved
• onRendered - after the route has rendered

For the full event payload types, see the RouterEvents type.

For a normal navigation, the events usually flow like this:

1. onBeforeNavigate
2. onBeforeLoad
3. onLoad
4. onBeforeRouteMount
5. onResolved
6. onRendered

You usually do not need every event. A good rule of thumb is:

• Use onBeforeNavigate or onBeforeLoad to observe navigation start
• Use onResolved for analytics and cleanup after navigation finishes
• Use onRendered for DOM-dependent work

Navigation events receive location change metadata describing what changed:

const unsubscribe = router.subscribe('onBeforeNavigate', (event) => {
  console.info({
    from: event.fromLocation?.href,
    to: event.toLocation.href,
    pathChanged: event.pathChanged,
    hrefChanged: event.hrefChanged,
    hashChanged: event.hashChanged,
  })
})

const unsubscribe = router.subscribe('onBeforeNavigate', (event) => {
  console.info({
    from: event.fromLocation?.href,
    to: event.toLocation.href,
    pathChanged: event.pathChanged,
    hrefChanged: event.hrefChanged,
    hashChanged: event.hashChanged,
  })
})

A few useful details:

• fromLocation can be undefined on the initial load
• pathChanged tells you whether the pathname changed
• hrefChanged includes pathname, search, and hash changes
• hashChanged is useful for distinguishing hash-only navigations

onResolved is a good default for analytics because it fires after navigation finishes:

const unsubscribe = router.subscribe('onResolved', ({ toLocation }) => {
  analytics.track('page_view', {
    path: toLocation.pathname,
    href: toLocation.href,
  })
})

const unsubscribe = router.subscribe('onResolved', ({ toLocation }) => {
  analytics.track('page_view', {
    path: toLocation.pathname,
    href: toLocation.href,
  })
})

If you use a mutation library without keyed mutation state, clear it after navigation:

const unsubscribe = router.subscribe('onResolved', ({ pathChanged }) => {
  if (pathChanged) {
    mutationCache.clear()
  }
})

const unsubscribe = router.subscribe('onResolved', ({ pathChanged }) => {
  if (pathChanged) {
    mutationCache.clear()
  }
})

Use onRendered when your side effect depends on the new route content already being in the DOM:

const unsubscribe = router.subscribe('onRendered', ({ toLocation }) => {
  focusPageHeading(toLocation.pathname)
})

const unsubscribe = router.subscribe('onRendered', ({ toLocation }) => {
  focusPageHeading(toLocation.pathname)
})

If you subscribe from a component or framework effect, always return the unsubscribe function from your cleanup so the listener is removed when the component unmounts.

• Router type
• RouterEvents type
• Data Mutations