Manage normal browser URL navigation
Browser single-page applications
TanStack · Function
createBrowserHistory
Creates the default browser history implementation for TanStack Router. Use its returned history object when you want to provide browser navigation history explicitly.
How it works
createBrowserHistory creates the browser-oriented history implementation used by TanStack Router. It relies on the browser History API, and the resulting history object can be passed to the Router constructor or router options.
Syntax
createBrowserHistory()Returns
A browser-oriented history instance compatible with TanStack Router's RouterHistory type.
Key points
- It is TanStack Router's standard history implementation for normal browser URL routing.
- Navigation is backed by the platform History API rather than a hash-only URL strategy.
- The returned object can be injected when constructing a Router.
- The API is provided by the @tanstack/history package as the browser-oriented history choice.
Common mistakes
- Creating an instance is optional in the usual browser setup because the router creates one automatically.
Example: Create and attach browser history
import { createBrowserHistory } from '@tanstack/react-router'
const history = createBrowserHistory()
const router = createRouter({
routeTree,
history,
})
// Later, when the history instance is no longer needed:
history.destroy()Creates browser-backed history and supplies it explicitly to a TanStack Router instance.
When to use it
Inject an explicitly created history object
Custom router construction
Create and later dispose of a controlled history instance
Testing router setup
Interview questions
QWhat does createBrowserHistory do?
It creates the default TanStack Router history implementation for browser routing. The implementation uses the browser's History API to manage navigation state.
Follow-up: What happens if no history is supplied? The router creates and uses a new createBrowserHistory instance automatically.
QHow do you use the returned value with a router?
Call createBrowserHistory to obtain a history object, then pass that object through the router's history option. This lets the router use that specific browser history instance.
Follow-up: Which option receives it? RouterOptions.history, whose type is RouterHistory.
QHow does browser history differ from hash history?
It is intended for browser routing and is the default history type. For hash-based URLs, use createHashHistory instead, which is a different history type.
Follow-up: When would browser history be inappropriate? When the application specifically needs URL fragments to represent navigation state, hash history is the relevant alternative.
Related
createHashHistoryRouterRouterOptions.historyRouterHistory