history - Algolia

This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.

Signature

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

Import

JavaScript

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

About this function

The history router is the default for the <InstantSearch> component’s 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.

If you’re using Next.js, see createInstantSearchRouterNext.

Examples

JavaScript

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

windowTitle

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.

JavaScript

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>
  );
}

createURL

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 query string or stringify an object. You can get more information from the qs documentation.
location (object). An alias to the implementation defined in getLocation. By default, it returns window.location.
routeState (object). The routeState created by the provided stateMapping. When absent, this is an untouched uiState.

JavaScript

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>
  );
}

parseURL

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.
location (object). An alias to the implementation defined in getLocation. By default, it returns window.location.

JavaScript

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>
  );
}

writeDelay

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.

JavaScript

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>
  );
}

getLocation

function

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.

JavaScript

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>
  );
}

push

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.

JavaScript

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>
  );
}

start

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.

JavaScript

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>
  );
}

dispose

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:

JavaScript

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>
  );
}

cleanUrlOnDispose

boolean

default:true

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.

JavaScript

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>
  );
}

React InstantSearch

​Import

​About this function

​Examples

​Options

Import

About this function

Examples

Options