Concepts / Building Search UI / Routing URLs
Feb. 14, 2019

Routing URLs

You are currently reading the documentation for InstantSearch.js V3. Read our migration guide to learn how to upgrade from V2 to V3. You can still find the V2 documentation here.

Overview

With the routing option, InstantSearch.js provides the necessary API entries to allow you to synchronize the state of your search UI (which widget were refined, what is the current search query …) with any kind of storage. And most probably you want that storage to be the browser URL bar.

Synchronizing your UI with the browser URL is a good practice. It allows any of your users to take one of your result pages, copy paste the browser URL and send it to a friend. It also allows your users to use the back and next button of their browser and always end up where they were previously.

By the end of this guide, you will be able to reproduce these examples:

Basic URLs

For a quick start, you can activate the default behaviour (here’s the live version):

1
2
3
4
5
const search = instantsearch({
  indexName: 'instant_search',
  routing: true
  searchClient,
});

The resulting URL in your browser URL bar will look like this:

https://website.com/?query=a&refinementList%5Bbrand%5D%5B0%5D=Drama

While not being pretty it is still very accurate: the query is a and the brand attribute, which is a refinementList, was refined (clicked) to Drama. But if you want something custom and clean, let’s move on to more user friendly URLs.

User-friendly URLs

In this part, you will be able to make URLs that map more clearly the refinements. At the end, you will get URLs that look like that:

https://website.com/?query=a&brands=Sony~Samsung&page=2

This way your users will be able to read them more easily when shared via emails, documents, social media…

To do so, the routing option accepts a simple boolean but also more complex objects to allow customization. The first customization option you want to use is stateMapping. It allows you to define more precisely how the state of your search will be synchronized to your browser URL bar (or any other router storage you might have).

Here’s an example achieving just that (and here’s the live version):

This example assumes that you have added the searchBox, refinementList and pagination widgets to your search UI. Then the refinementList is activated on the brands attribute. Please adjust given your own data.

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
const search = instantsearch({
  indexName: 'instant_search',
  searchClient,
  routing: {
    stateMapping: {
      stateToRoute(uiState) {
        return {
          query: uiState.query,
          // we use the character ~ as it is one that is rarely present in data and renders well in URLs
          brands:
            uiState.refinementList &&
            uiState.refinementList.brand &&
            uiState.refinementList.brand.join('~'),
          page: uiState.page
        };
      },
      routeToState(routeState) {
        return {
          query: routeState.query,
          refinementList: {
            brand: routeState.brands && routeState.brands.split('~')
          },
          page: routeState.page
        };
      }
    }
  }
});

There’s a lifecycle in which when the stateMapping functions are called:

  • stateToRoute is called whenever widgets are refined (clicked). It is also called every time any widget needs to create a URL.
  • routeToState is called whenever the user loads, reloads the page or clicks on the back/next buttons of the browser.

To build your own mapping easily, just console.log(uiState) and see what you’re getting. Note that the object you return in stateToRoute will be the one you’ll receive as an argument in routeToState.

SEO friendly URLs

URLs are more than just query parameters (with the question mark) and one other important part is the path of the URL. In this part, you will end up with URLs that look like that:

https://website.com/search/q/phone/brands/Sony~Samsung/p/1

Be it for SEO benefits or to align your search UI URLs with your current sitemap and existing URL scheme.

Example of implementation

Here’s an example achieving just that (and here’s the live version):

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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
const search = instantsearch({
  indexName: 'instant_search',
  searchClient,
  routing: {
    router: instantsearch.routers.history({
      windowTitle(routeState) {
        return `Website / Find ${routeState.q} in ${routeState.brands} brands`;
      },
      createURL({ routeState, location }) {
        let baseUrl = location.href.split('/search/')[0];

        if (
          !routeState.q &&
          routeState.brands === 'all' &&
          routeState.p === 1
        ) {
          return baseUrl;
        }

        if (baseUrl[baseUrl.length - 1] !== '/') {
          baseUrl += '/';
        }

        const routeStateArray = [
          'q',
          encodeURIComponent(routeState.q),
          'brands',
          encodeURIComponent(routeState.brands),
          'p',
          routeState.p
        ];

        return `${baseUrl}search/${routeStateArray.join('/')}`;
      },
      parseURL({ location }) {
        const routeStateString = location.href.split('/search/')[1];

        if (routeStateString === undefined) {
          return {};
        }

        const routeStateValues = routeStateString.match(
          /^q\/(.*?)\/brands\/(.*?)\/p\/(.*?)$/
        );

        return {
          q: decodeURIComponent(routeStateValues[1]),
          brands: decodeURIComponent(routeStateValues[2]),
          p: routeStateValues[3]
        };
      },
    }),
    stateMapping: {
      stateToRoute(uiState) {
        return {
          q: uiState.query || '',
          brands:
            (uiState.refinementList &&
              uiState.refinementList.brand &&
              uiState.refinementList.brand.join('~')) ||
            'all',
          p: uiState.page || 1
        };
      },
      routeToState(routeState) {
        if (routeState.brands === 'all') {
          // eslint-disable-next-line no-param-reassign
          routeState.brands = undefined;
        }

        return {
          query: routeState.q,
          refinementList: {
            brand: routeState.brands && routeState.brands.split('~'),
          },
          page: routeState.p
        };
      }
    }
  }
});

As you can see, we are now using the instantsearch.routers.history so that we can explicitly set options on the default router mechanism used in the previous example. What we see also is that both the router and stateMapping options can be used together as a way to easily map uiState to routeState and vice versa.

Using that we can configure:

  • windowTitle: This method can be used to map the object (routeState) returned from stateToRoute to your window title
  • createURL: This method is called everytime we need to create a URL. When we want to synchronize the routeState to the browser URL bar, when we want to render <a href> tags in the menu widget or when you call createURL in one of your connectors’s rendering method
  • parseURL: This method is called everytime the user loads, reloads the page or click on back/next buttons of the browser

About SEO

For your search results to be part of search engines results, you will have to selectively choose them. Trying to have all of your search results inside search engines could be considered as spam by them.

To do that, you can create a robots.txt and host it at https://website.com/robots.txt.

Here’s an example one based on the URL scheme we created.

1
2
3
4
5
User-agent: *
Allow: /search/q/phones/brands/Samsung/p1
Allow: /search/q/phones/brands/Apple/p1
Disallow: /search/
Allow: *

References

instantsearch.routers.history API

InstantSearch.js provides a default router under instantsearch.routers.history. You can use it when you want to go futher than just aliasing query string parameters in the URL. For example, if you want to generate URLs like https://website.com/search/q/phone/brands/Sony~Samsung/p/1.

The signature is the following: history({ windowTitle, createURL, parseURL, writeDelay }).

windowTitle: function(routeState): string

This function allows you to dynamically customize the window title based on the provided routeState. This function is called every time the user refines the UI, after the history timer.

createURL: function({ qsModule, location, routeState }): string

This function allows you to directly change the format of URLs that will be created and rendered to the browser URL bar or widgets.

This function is called everytime InstantSearch.js needs to create a URL. The provided options are:

  • qsModule: object. A query string parsing and stringifying module (see documentation). We use it internally so we provide it to you as a convenience
  • location: object. Alias to window.location
  • routeState: object. The routeState created by the stateMapping provided. When no stateMapping is provided, this is an untouched uiState

parseURL: function({qsModule, location}): object

This function is responsible for parsing back the URL string to a routeState. This function must be customized if you customized the createURL function. This function is called everytime the user loads, reloads or click on back/next buttons of the browser. The provided options are:

  • qsModule: object, a query string parsing and stringifying module (see documentation). We use it internally so we provide it to you as a convenience.
  • location: function, alias to window.location.

writeDelay: number = 400

This option controls the number of milliseconds to wait before writing the new URL to the browse URL bar. You can think about it this way: “400ms after the last user action, let’s save it to the browser URL bar”. Which helps in reducing:

  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 bar too often. We have seen recurring but hard to track performance issues of updating the browser URL bar too often due to a lot of browser extensions reacting to it

400ms is a good guesstimate from our experience to consider a user action “done” and thus save it to the URL.

uiState object reference

The routeState object shape is completely up to you and thus not part of any public API.

But the uiState object is created by InstantSearch.js internally and thus part of a public API. Every widget inside the library has its own way of updating it. Here’s a complete uiState of all widgets. So that you can easily see, given the widgets you use, what you will receive:

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
31
32
33
{
  query: 'Hill valley',
  menu: {
    type: 'antique'
  },
  hierarchicalMenu: {
    category: ['Decoration > Clocks']
  },
  refinementList: {
    colors: ['white', 'black']
  },
  numericRefinementList: {
    heightInCm: 40
  },
  numericSelector: {
    widthInCm: 30
  },
  priceRanges: {
    price: '200:20000'
  },
  range: {
    ageInYears: '2:10'
  },
  starRating: {
    rating: 3
  },
  toggle: {
    freeShipping: true
  },
  sortBy: 'most_popular_index',
  page: 2,
  hitsPerPage: 20
}

Did you find this page helpful?