> ## 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 React InstantSearch.

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>
  This is the **React InstantSearch v7** documentation.
  If you're upgrading from v6, see the [upgrade guide](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-v6-to-react-instantsearch-v7).
  If you were using React InstantSearch Hooks,
  this v7 documentation applies—just check for [necessary changes](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-hooks-to-react-instantsearch-v7).
  To continue using v6, you can find the [archived documentation](https://algolia.com/old-docs/deprecated/instantsearch/react/v6/api-reference/instantsearch/).
</Note>

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

## Import

```js JavaScript icon=code theme={"system"}
import { history } from "instantsearch.js/es/lib/routers";
```

## About this function

The `history` router is the default for the `<InstantSearch>` component's [routing](/doc/api-reference/widgets/instantsearch/react#param-routing) prop.

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/react).

<Info>
  If you're using Next.js, see [`createInstantSearchRouterNext`](/doc/api-reference/widgets/instantsearch-next-router/react).
</Info>

## Examples

```jsx JavaScript icon=code theme={"system"}
import { InstantSearch } from "react-instantsearch";
import { history } from "instantsearch.js/es/lib/routers";

const routing = {
  router: history(),
};

function App() {
  return (
    <InstantSearch
      searchClient={searchClient}
      indexName="instant_search"
      routing={routing}
    >
      {/* ... */}
    </InstantSearch>
  );
}
```

## 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.

  ```jsx JavaScript icon=code theme={"system"}
  import { InstantSearch } from "react-instantsearch";
  import { history } from "instantsearch.js/es/lib/routers";

  const routing = {
    router: history({
      windowTitle(routeState) {
        const indexState = routeState.indexName || {};

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

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

  function App() {
    return (
      <InstantSearch
        searchClient={searchClient}
        indexName="instant_search"
        routing={routing}
      >
        {/* ... */}
      </InstantSearch>
    );
  }
  ```
</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`.

  ```jsx JavaScript icon=code theme={"system"}
  import { InstantSearch } from "react-instantsearch";
  import { history } from "instantsearch.js/es/lib/routers";

  const routing = {
    router: 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}`;
      },
    }),
  };

  function App() {
    return (
      <InstantSearch
        searchClient={searchClient}
        indexName="instant_search"
        routing={routing}
      >
        {/* ... */}
      </InstantSearch>
    );
  }
  ```
</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`.

  ```jsx JavaScript icon=code theme={"system"}
  import { InstantSearch } from "react-instantsearch";
  import { history } from "instantsearch.js/es/lib/routers";

  const routing = {
    router: history({
      parseURL({ qsModule, location }) {
        return qsModule.parse(location.search.slice(1));
      },
    }),
  };

  function App() {
    return (
      <InstantSearch
        searchClient={searchClient}
        indexName="instant_search"
        routing={routing}
      >
        {/* ... */}
      </InstantSearch>
    );
  }
  ```
</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`.

  ```jsx JavaScript icon=code theme={"system"}
  import { InstantSearch } from "react-instantsearch";
  import { history } from "instantsearch.js/es/lib/routers";

  const routing = {
    router: history({
      writeDelay: 400,
    }),
  };

  function App() {
    return (
      <InstantSearch
        searchClient={searchClient}
        indexName="instant_search"
        routing={routing}
      >
        {/* ... */}
      </InstantSearch>
    );
  }
  ```
</ParamField>

<ParamField body="getLocation" type="function" post={["default: () => window.location"]}>
  This function lets you return a custom implementation of \[`Location`]\([https://developer](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.

  ```jsx JavaScript icon=code theme={"system"}
  import { InstantSearch } from "react-instantsearch";
  import { history } from "instantsearch.js/es/lib/routers";

  // Provide `serverUrl` from your server.
  function App({ serverUrl }) {
    const routing = {
      router: history({
        getLocation() {
          if (typeof window !== "undefined") {
            return window.location;
          }

          return new URL(serverUrl);
        },
      }),
    };

    return (
      <InstantSearch
        searchClient={searchClient}
        indexName="instant_search"
        routing={routing}
      >
        {/* ...*/}
      </InstantSearch>
    );
  }
  ```
</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.

  ```jsx JavaScript icon=code theme={"system"}
  import { InstantSearch } from "react-instantsearch";
  import { history } from "instantsearch.js/es/lib/routers";
  import { useRouter } from "third-party-router";

  function App() {
    const thirdPartyRouter = useRouter();

    const routing = {
      router: history({
        push(url) {
          thirdPartyRouter.push(url);
        },
      }),
    };

    return (
      <InstantSearch
        searchClient={searchClient}
        indexName="instant_search"
        routing={routing}
      >
        {/* ... */}
      </InstantSearch>
    );
  }
  ```
</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.

  ```jsx JavaScript icon=code theme={"system"}
  import { InstantSearch } from "react-instantsearch";
  import { history } from "instantsearch.js/es/lib/routers";
  import { useRouter } from "third-party-router";

  function App() {
    const thirdPartyRouter = useRouter();

    const routing = {
      router: history({
        start(onUpdate) {
          thirdPartyRouter.addEventListener("routeChange", () => onUpdate());
        },
      }),
    };

    return (
      <InstantSearch
        searchClient={searchClient}
        indexName="instant_search"
        routing={routing}
      >
        {/* ...*/}
      </InstantSearch>
    );
  }
  ```
</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:

  ```jsx JavaScript icon=code theme={"system"}
  import { InstantSearch } from "react-instantsearch";
  import { history } from "instantsearch.js/es/lib/routers";
  import { useRouter } from "third-party-router";

  function App() {
    const thirdPartyRouter = useRouter();
    // We need to keep a stable reference to the event listener so that we can remove it later.
    const routeChangeEventRef = useRef(null);

    const routing = {
      router: history({
        start(onUpdate) {
          routeChangeEventRef.current = () => onUpdate();
          thirdPartyRouter.addEventListener(
            "routeChange",
            routeChangeEventRef.current,
          );
        },
        dispose() {
          thirdPartyRouter.removeEventListener(
            "routeChange",
            routeChangeEventRef.current,
          );
        },
      }),
    };

    return (
      <InstantSearch
        searchClient={searchClient}
        indexName="instant_search"
        routing={routing}
      >
        {/* ... */}
      </InstantSearch>
    );
  }
  ```
</ParamField>

<ParamField body="cleanUrlOnDispose" type="boolean" default={true} post={['since: v7.5.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.

  ```jsx JavaScript icon=code theme={"system"}
  import { InstantSearch } from "react-instantsearch";
  import { history } from "instantsearch.js/es/lib/routers";

  const routing = {
    router: history({
      cleanUrlOnDispose: false,
    }),
  };

  function App() {
    return (
      <InstantSearch
        searchClient={searchClient}
        indexName="instant_search"
        routing={routing}
      >
        {/*...*/}
      </InstantSearch>
    );
  }
  ```
</ParamField>