Skip to content
XMachines

Function: createBrowserHistory()

API / @xmachines/play-dom-router / createBrowserHistory

function createBrowserHistory(options): BrowserHistory;

Defined in: play-dom-router/src/create-browser-history.ts:120

Create browser history that wraps window.history

Aligned with TanStack Router’s history interface for API parallelism.

Architecture:

  • Patches window.history.pushState/replaceState to detect changes
  • Listens to popstate for browser back/forward
  • Provides subscribe() for listeners (like PlayRouterProvider)
  • Testable (accepts window object)

Usage:

const history = createBrowserHistory({ window });


const unsubscribe = history.subscribe((location) => {
  console.log("URL changed:", location.pathname);
});


history.push("/new-path");


// Later:
unsubscribe();
history.destroy();

destroy() is idempotent and cooperates with other wrappers created for the same window instance.

Warning: createBrowserHistory() mutates global window.history methods (pushState and replaceState) and coordinates wrappers with shared ref-count state. To mitigate leakage, create one history wrapper per browser window at the application boundary and always pair it with destroy() during teardown.

Parameters

ParameterType
options{ window: BrowserWindow; }
options.windowBrowserWindow

Returns

BrowserHistory