Multi-Index Search with InstantSearch.js

You are currently reading the documentation for InstantSearch.js V4. Read our migration guide to learn how to upgrade from V3 to V4. You can still access the V3 documentation for this page.

Multi-index search, or federated search, lets you search multiple data sources at once with the same query and gather results in a single search experience. This is a common pattern when building autocomplete search experiences, but also to offer centralized access to multiple sources of content developed and curated independently.

Multi-index search can also help you achieve complex UIs that display the content of the same index in several ways, for example to surface top-rated items before the list of results.

• Synchronize two InstantSearch indices and share a single search box to display multiple hits from different indices.
• Use Autocomplete to target multiple indices

The source code for both examples is on GitHub.

Synchronize two InstantSearch indices

This example uses a single searchBox to search multiple indices. It adds the first hits widget at the top level, while the second one is scoped under an index widget. The second hits widget just displays results from the Algolia index referenced by the index widget that precedes it. The first hits widget displays results from the top level instant_search index.

All examples in this guide assume you’re including InstantSearch.js in your web page via a CDN. If you’re using it with a package manager, you should adjust the way you import InstantSearch.js and its widgets. Read How to install InstantSearch.js for more information.

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
const search = instantsearch({
  indexName: 'instant_search',
  searchClient,
});

search.addWidgets([
  instantsearch.widgets.searchBox({
    container: '#searchbox',
  }),

  instantsearch.widgets.hits({
    container: '#hits-instant-search',
    templates: {
      item:
        '{{#helpers.highlight}}{ "attribute": "name" }{{/helpers.highlight}}',
    },
  }),

  instantsearch.widgets
    .index({ indexName: 'instant_search_price_desc' })
    .addWidgets([
      instantsearch.widgets.hits({
        container: '#hits-instant-search-price-desc',
        templates: {
          item:
            '{{#helpers.highlight}}{ "attribute": "name" }{{/helpers.highlight}}',
        },
      }),
    ]),
]);

search.start();

You can scope widget under an index. The following example displays a different number of hits for the two sets of results. The instant_search index displays 8 results and instant_search_price_desc 16 results. To restrict the number of results per page, use the configure widget. Each widget is scoped under the targeted level.

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
const search = instantsearch({
  indexName: 'instant_search',
  searchClient,
});

search.addWidgets([
  instantsearch.widgets.configure({
    hitsPerPage: 8,
  }),

  instantsearch.widgets.searchBox({
    container: '#searchbox',
  }),

  instantsearch.widgets.hits({
    container: '#hits-instant-search',
    templates: {
      item:
        '{{#helpers.highlight}}{ "attribute": "name" }{{/helpers.highlight}}',
    },
  }),

  instantsearch.widgets
    .index({ indexName: 'instant_search_price_desc' })
    .addWidgets([
      instantsearch.widgets.configure({
        hitsPerPage: 16,
      }),

      instantsearch.widgets.hits({
        container: '#hits-instant-search-price-desc',
        templates: {
          item:
            '{{#helpers.highlight}}{ "attribute": "name" }{{/helpers.highlight}}',
        },
      }),
    ]),
]);

search.start();

You can find the complete example on GitHub.

Build a multi-source autocomplete experience

One of the most common use cases of multi-index search is when you’re building an autocomplete experience. For example, you may want to display Query Suggestions together with recent searches, create a multi-column layout mixing facets and item previews, or even dynamically change sources based on the query.

You can use the Autocomplete library in your InstantSearch app to build a dynamic multi-source autocomplete experience. Autocomplete isn’t limited to Algolia indices, so you can even use static sources or fetch data from other APIs.