> ## 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 = () =>
search query
;
export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
FlavorSwitcher requires at least one option.
;
}
const selected = options.find(option => option.value === current) ?? options[0];
return ;
};
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/).
```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 `` 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).
If you're using Next.js, see [`createInstantSearchRouterNext`](/doc/api-reference/widgets/instantsearch-next-router/react).
## 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 (
{/* ... */}
);
}
```
## Options
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 (
{/* ... */}
);
}
```
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 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 (
{/* ... */}
);
}
```
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 (
{/* ... */}
);
}
```
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 (
{/* ... */}
);
}
```
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 (
{/* ...*/}
);
}
```
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 (
{/* ... */}
);
}
```
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 (
{/* ...*/}
);
}
```
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 (
{/* ... */}
);
}
```
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 (
{/*...*/}
);
}
```