> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# history

> Synchronizes the search UI state with the browser URL in InstantSearch.js.

export const SearchQuery = () => <Tooltip tip="The text users enter into a search box. In the Search API, this corresponds to the query parameter. A search query is often used with filters, facets, and other parameters, but these aren't part of the query text itself.">
    search query
  </Tooltip>;

<Note>
  You are viewing the documentation for **InstantSearch.js v4**.
  To upgrade from v3, see the [migration guide](/doc/guides/building-search-ui/upgrade-guides/js#upgrade-from-v3-to-v4).
  Looking for the v3 version of this page?
  [View the v3 docs](https://algolia.com/old-docs/deprecated/instantsearch/js/v3/api-reference/history-router).
</Note>

```ts Signature theme={"system"}
history({
  // Optional parameters
  windowTitle?: function,
  createURL?: function,
  parseURL?: function,
  writeDelay?: number,
  getLocation?: function,
  push?: function,
  start?: function,
  dispose?: function,
  cleanUrlOnDispose?: boolean,
});
```

## Import

<CodeGroup>
  ```js Package manager theme={"system"}
  import { history } from "instantsearch.js/es/lib/routers";
  ```

  ```js CDN theme={"system"}
  const { history } = instantsearch.routers;
  // or directly use instantsearch.routers.history()
  ```
</CodeGroup>

## About this widget

The `history` router is the default for the `instantsearch` object's [routing](/doc/api-reference/widgets/instantsearch/js#param-routing) option.

The router provides an API that lets you customize some of its behaviors.
To get a sense of what you can do with the API, see [Routing URLs](/doc/guides/building-search-ui/going-further/routing-urls/js).

## Examples

```js JavaScript icon=code theme={"system"}
instantsearch({
  // ...
  routing: {
    router: history(),
  },
});
```

## Options

<ParamField body="windowTitle" type="function">
  This function lets you dynamically customize the window title based on the provided `routeState`.
  It's called every time users refine the UI and the history timer completes.

  ```js JavaScript icon=code theme={"system"}
  history({
    windowTitle(routeState) {
      const indexState = routeState.indexName || {};

      if (!indexState.query) {
        return "MyWebsite - Results page";
      }

      return `MyWebsite - Results for: ${indexState.query}`;
    },
  });
  ```
</ParamField>

<ParamField body="createURL" type="function">
  This function lets you directly change the format of URLs that are created and rendered for the browser URL bar or widgets. It's called every time InstantSearch needs to create a URL. The provided options are:

  * `qsModule` (object). A module that can parse a <SearchQuery /> string or stringify an object. You can get more information from the [qs documentation](https://github.com/ljharb/qs).
  * `location` (object). An alias to the implementation defined in [`getLocation`](/doc/api-reference/widgets/history-router/react#param-get-location). By default, it returns `window.location`.
  * `routeState` (object). The `routeState` created by the provided `stateMapping`. When absent, this is an untouched `uiState`.

  ```js JavaScript icon=code theme={"system"}
  history({
    createURL({ qsModule, location, routeState }) {
      const { origin, pathname, hash } = location;
      const indexState = routeState["instant_search"] || {};
      const queryString = qsModule.stringify(routeState);

      if (!indexState.query) {
        return `${origin}${pathname}${hash}`;
      }

      return `${origin}${pathname}?${queryString}${hash}`;
    },
  });
  ```
</ParamField>

<ParamField body="parseURL" type="function">
  This function is responsible for parsing the URL string back into a `routeState`. It must be customized if you customized the `createURL` function. It's called every time a user loads or reloads a page, or when they click on the back or next buttons of the browser. The provided options are:

  * `qsModule` (object). A module that can parse a query string or stringify an object. You can get more information from the [qs documentation](https://github.com/ljharb/qs).
  * `location` (object). An alias to the implementation defined in [`getLocation`](/doc/api-reference/widgets/history-router/react#param-get-location). By default, it returns `window.location`.

  ```js JavaScript icon=code theme={"system"}
  history({
    parseURL({ qsModule, location }) {
      return qsModule.parse(location.search.slice(1));
    },
  });
  ```
</ParamField>

<ParamField body="writeDelay" type="number" default={400}>
  This option controls the number of milliseconds the router waits before writing the new URL to the browser.
  You can think about it this way: "400 ms after the last user action, the URL is pushed to the browser".
  This helps reduce:

  * The number of different history entries. If you type "phone", you don't want to have 5 history entries and thus have to click 5 times on the back button to go back to the previous search state
  * The performance overhead of updating the browser URL too often. There are recurring but hard to track performance issues associated with updating the browser URL too often: these issues result from browser extensions reacting to every change.

  400 ms is a typically a pretty good `writeDelay`.

  ```js JavaScript icon=code theme={"system"}
  history({
    writeDelay: 400,
  });
  ```
</ParamField>

<ParamField body="getLocation" type="function" post={["default: () => window.location"]}>
  This function lets you return a custom implementation of [`Location`](https://developer.mozilla.org/en-US/docs/Web/API/Location).
  It enables support for routing in server environments where `window` isn't available.

  By default, it generates an error if there isn't a custom implementation outside a browser environment.

  ```js JavaScript icon=code theme={"system"}
  history({
    getLocation() {
      if (typeof window === "undefined") {
        const url = "..."; // retrieved from the server context
        return new URL(url);
      }

      return window.location;
    },
  });
  ```
</ParamField>

<ParamField body="push" type="function">
  This function lets you customize the behavior of the router when it pushes a new URL so that you can delegate it to a third party router or set a custom history state.
  It's called every time users refine the UI and the history timer completes.
  The provided option is:

  * `url` (string). The URL which needs to be pushed to the browser.

  ```js JavaScript icon=code theme={"system"}
  history({
    push(url) {
      thirdPartyRouter.push(url);
    },
  });
  ```
</ParamField>

<ParamField body="start" type="function">
  This function is called when the router starts.
  You can use it to synchronize InstantSearch's router with a third party router by hooking events to it.
  The provided option is:

  * `onUpdate: () => void`. A function that needs to call to inform InstantSearch that the URL has changed.

  ```js JavaScript icon=code theme={"system"}
  history({
    start(onUpdate) {
      thirdPartyRouter.addEventListener("routeChange", () => {
        onUpdate();
      });
    },
  });
  ```
</ParamField>

<ParamField body="dispose" type="function">
  This function is called when the router gets disposed of.
  You can use it to detach events you may have set in `start`.
  The provided option is:

  ```js JavaScript icon=code theme={"system"}
  let handler;

  history({
    start(onUpdate) {
      handler = () => onUpdate();
      thirdPartyRouter.addEventListener("routeChange", handler);
    },
    dispose() {
      thirdPartyRouter.removeEventListener("routeChange", handler);
    },
  });
  ```
</ParamField>

<ParamField body="cleanUrlOnDispose" type="boolean" default={true} post={['since: v4.63.0']}>
  This option controls whether the URL is cleaned up from active refinements when the router is disposed of.
  It's useful when the search experience is in a modal,
  to remove query parameters from the URL when the modal is closed.

  ```js JavaScript icon=code theme={"system"}
  history({
    cleanUrlOnDispose: false,
  });
  ```
</ParamField>