> ## 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 Vue 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>;

```ts Signature theme={"system"}
import { history } from 'instantsearch.js/es/lib/routers';

history({
  // Optional parameters
  windowTitle: function,
  createURL: function,
  parseURL: function,
  writeDelay: number,
  getLocation: function,
  push: function,
  start: function,
  dispose: function,
  cleanUrlOnDispose: boolean,
});
```

## About this widget

The `history` router is the default for the `ais-instant-search` wrapper's [routing](/doc/api-reference/widgets/instantsearch/vue#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/vue).

## Examples

```vue Vue icon=code theme={"system"}
<template>
  <ais-instant-search
    [...] 
    :routing="routing"
  >
    <!-- Widgets -->
  </ais-instant-search>
</template>

<script>
import { history } from "instantsearch.js/es/lib/routers";

export default {
  data() {
    return {
      // ...
      routing: {
        router: history(),
      },
    };
  },
};
</script>
```

## 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/vue#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 || {};
      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/vue#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 event handlers to it. The provided option is:

  * `onUpdate: () => void`. A function that needs to call to inform InstantSearch that the URL has changed. It will read the current URL and update the UI state accordingly.

  ```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 event handlers 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.13.2']}>
  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>