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:122

Creates a browser history that wraps window.history

The interface is the same as the history interface of TanStack Router, so that the two APIs stay parallel.

Architecture:

  • It patches window.history.pushState and window.history.replaceState, to detect a change
  • It listens for popstate, for the browser BACK and FORWARD buttons
  • It gives you subscribe() for a listener, such as PlayRouterProvider
  • It accepts a window object, so a test can give a double

Use:

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 it cooperates with each other wrapper of the same window instance.

Warning: createBrowserHistory() changes the global window.history methods (pushState and replaceState), and it coordinates the wrappers with a shared reference count. Therefore create one history wrapper for each browser window, at the boundary of the application, and always call destroy() during the teardown.

Parameters

ParameterType
options{ window: BrowserWindow; }
options.windowBrowserWindow

Returns

BrowserHistory