API Reference / React InstantSearch Hooks / history

history

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

history({
  // Optional parameters
  windowTitle: function,
  createURL: function,
  parseURL: function,
  writeDelay: number,
  getLocation: function,
});
See code examples

About this widget

The history router is the one used by default within <InstantSearch>.

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 the dedicated guide on Routing URLs.

Examples

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

import { InstantSearch } from 'react-instantsearch-hooks-web';
import { history } from 'instantsearch.js/es/lib/routers';

function App() {
  const routing = useMemo(() => ({
    router: history(),
  }));

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

Options

windowTitle
type: function
Optional

This function lets you dynamically customize the window title based on the provided routeState. It’s called every time the user refines the UI and the history timer completes.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

import { InstantSearch } from 'react-instantsearch-hooks-web';
import { history } from 'instantsearch.js/es/lib/routers';

function App() {
  const routing = useMemo(() => ({
    router: history({
      windowTitle(routeState) {
        const indexState = routeState.indexName || {}

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

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

  return (
    <InstantSearch
      searchClient={searchClient}
      indexName="instant_search"
      routing={router}
    >
      {/* ... */}
    </InstantSearch>
  );
}
createURL
type: function
Optional

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.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

import { InstantSearch } from 'react-instantsearch-hooks-web';
import { history } from 'instantsearch.js/es/lib/routers';

function App() {
  const routing = useMemo(() => ({
    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}`;
      },
    }),
  }));

  return (
    <InstantSearch
      searchClient={searchClient}
      indexName="instant_search"
      routing={router}
    >
      {/* ... */}
    </InstantSearch>
  );
}
parseURL
type: function
Optional

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.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

import { InstantSearch } from 'react-instantsearch-hooks-web';
import { history } from 'instantsearch.js/es/lib/routers';

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

  return (
    <InstantSearch
      searchClient={searchClient}
      indexName="instant_search"
      routing={router}
    >
      {/* ... */}
    </InstantSearch>
  );
}
writeDelay
type: number
default: 400
Optional

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:

  1. 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
  2. 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.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

import { InstantSearch } from 'react-instantsearch-hooks-web';
import { history } from 'instantsearch.js/es/lib/routers';

function App() {
  const routing = useMemo(() => ({
    router: history({
      writeDelay: 400,
    }),
  }));

  return (
    <InstantSearch
      searchClient={searchClient}
      indexName="instant_search"
      routing={router}
    >
      {/* ... */}
    </InstantSearch>
  );
}
getLocation
type: function
default: () => window.location
Optional

This function lets you return a custom implementation of 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.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

import { InstantSearch } from 'react-instantsearch-hooks-web';
import { history } from 'instantsearch.js/es/lib/routers';

function App() {
  const routing = useMemo(() => ({
    router: history({
      getLocation() {
        if (typeof window === 'undefined') {
          const url = '...'; // retrieved from the server context
          return new URL(url);
        }

        return window.location;
      },
    }),
  }));

  return (
    <InstantSearch
      searchClient={searchClient}
      indexName="instant_search"
      routing={router}
    >
      {/* ... */}
    </InstantSearch>
  );
}
Did you find this page helpful?
React InstantSearch Hooks v6