History API

History

History management for browser navigation, including browser history, hash history, and memory history.

RouterHistory

The history interface used by TanStack Router.

location · HistoryLocation

The current location object.

length · number

Number of entries in the history stack.

push · (path: string, state?: any) => void

Push a new entry onto the history stack.

history.push('/posts', { from: 'homepage' })

replace · (path: string, state?: any) => void

Replace the current history entry.

history.replace('/login')

go · (delta: number) => void

Move through the history stack by a delta.

history.go(-2)  // Go back 2 entries
history.go(1)   // Go forward 1 entry

back · () => void

Go back one entry in the history stack.

history.back()

forward · () => void

Go forward one entry in the history stack.

history.forward()

subscribe · (callback: (event) => void) => () => void

Subscribe to history changes. Returns unsubscribe function.

const unsubscribe = history.subscribe((event) => {
  console.log('Navigation:', event.location)
})

block · (blocker: NavigationBlocker) => () => void

Block navigation and show confirmation. Returns unblock function.

const unblock = history.block(async ({ currentLocation, nextLocation }) => {
  return window.confirm('Are you sure you want to leave?')
})

createHref · (path: string) => string

Create an href string from a path.

const href = history.createHref('/posts')

HistoryLocation

Represents a location in the history stack.

href · string

The full URL string.

pathname · string

The path portion of the URL.

search · string

The search/query string portion of the URL.

hash · string

The hash portion of the URL.

state · HistoryState

State associated with this history entry.

createBrowserHistory

Create a history object that uses the browser’s History API.

import { createBrowserHistory } from '@tanstack/react-router'

const history = createBrowserHistory()

const router = createRouter({
  routeTree,
  history
})

Options

window · Window

The window object to use. Defaults to global window.

createHashHistory

Create a history object that uses URL hash for navigation.

import { createHashHistory } from '@tanstack/react-router'

const history = createHashHistory()

const router = createRouter({
  routeTree,
  history
})

Use case: Useful for apps hosted on static file servers or when you can’t configure server-side routing.

Options

window · Window

The window object to use. Defaults to global window.

createMemoryHistory

Create a history object that stores navigation in memory (no browser integration).

import { createMemoryHistory } from '@tanstack/react-router'

const history = createMemoryHistory({
  initialEntries: ['/'],
  initialIndex: 0
})

const router = createRouter({
  routeTree,
  history
})

Use case: Testing, server-side rendering, or non-browser environments.

Options

initialEntries · string[]

Initial history entries.

Default: ['/']

initialIndex · number

Initial position in the history stack.

Default: 0

NavigationBlocker

Interface for blocking navigation.

blockerFn · BlockerFn · required

Function called when navigation is attempted.

async ({ currentLocation, nextLocation, action }) => {
  return window.confirm('Leave this page?')
}

enableBeforeUnload · boolean | (() => boolean)

Enable browser’s beforeunload event.

enableBeforeUnload: true
enableBeforeUnload: () => form.isDirty

BlockerFn

Function signature for navigation blockers.

args.currentLocation · HistoryLocation

The current location.

args.nextLocation · HistoryLocation

The location being navigated to.

args.action · 'PUSH' | 'REPLACE' | 'POP'

The type of navigation action.

Returns: boolean | Promise<boolean> - True to allow navigation, false to block.

Examples

Basic Browser History

import { createBrowserHistory, createRouter } from '@tanstack/react-router'

const history = createBrowserHistory()

const router = createRouter({
  routeTree,
  history,
  basepath: '/app'
})

Hash History for Static Hosting

import { createHashHistory } from '@tanstack/react-router'

const history = createHashHistory()

const router = createRouter({
  routeTree,
  history
})

// URLs will be like: https://example.com/#/posts/123

Memory History for Testing

import { createMemoryHistory } from '@tanstack/react-router'
import { render } from '@testing-library/react'

test('navigates to post detail', async () => {
  const history = createMemoryHistory({
    initialEntries: ['/posts']
  })
  
  const router = createRouter({
    routeTree,
    history
  })
  
  const { getByText } = render(
    <RouterProvider router={router} />
  )
  
  // Test navigation...
})

Navigation Blocking

import { useBlocker } from '@tanstack/react-router'

function EditForm() {
  const [isDirty, setIsDirty] = useState(false)
  
  useBlocker({
    blockerFn: async () => {
      if (isDirty) {
        return window.confirm(
          'You have unsaved changes. Are you sure you want to leave?'
        )
      }
      return true
    },
    enableBeforeUnload: isDirty
  })
  
  return (
    <form onChange={() => setIsDirty(true)}>
      {/* form fields */}
    </form>
  )
}

Custom History Events

import { createBrowserHistory } from '@tanstack/react-router'

const history = createBrowserHistory()

// Subscribe to all navigation events
const unsubscribe = history.subscribe((event) => {
  console.log('Navigation:', {
    type: event.action.type,
    location: event.location
  })
  
  // Analytics tracking
  analytics.track('pageview', {
    path: event.location.pathname
  })
})

// Clean up subscription
unsubscribe()

Programmatic Navigation

function useCustomNavigation() {
  const router = useRouter()
  const history = router.history
  
  const navigateBack = () => {
    if (history.length > 1) {
      history.back()
    } else {
      history.push('/')
    }
  }
  
  const navigateToLogin = () => {
    history.push('/login', {
      returnTo: router.state.location.pathname
    })
  }
  
  return { navigateBack, navigateToLogin }
}

Server-Side Rendering

import { createMemoryHistory } from '@tanstack/react-router'

export async function renderToString(url: string) {
  const history = createMemoryHistory({
    initialEntries: [url]
  })
  
  const router = createRouter({
    routeTree,
    history
  })
  
  await router.load()
  
  return renderToString(
    <RouterProvider router={router} />
  )
}

Custom History Implementation

import { createHistory } from '@tanstack/history'

const customHistory = createHistory({
  getLocation: () => ({
    href: window.location.href,
    pathname: window.location.pathname,
    search: window.location.search,
    hash: window.location.hash,
    state: window.history.state || {}
  }),
  
  getLength: () => window.history.length,
  
  pushState: (path, state) => {
    window.history.pushState(state, '', path)
  },
  
  replaceState: (path, state) => {
    window.history.replaceState(state, '', path)
  },
  
  go: (delta) => {
    window.history.go(delta)
  },
  
  back: () => {
    window.history.back()
  },
  
  forward: () => {
    window.history.forward()
  },
  
  createHref: (path) => path
})