InstantSearch.js FAQ

The ratingMenu doesn’t support float values. You can store an integer representation of this value in your records (for example, 0.5 * 10 = 5) and display the original value in your UI.

To search only when the query is longer than a certain length, you can implement a proxy search client. Then, you can add a condition, for example, query.length > 3.

The uiState only works when the widgets responsible for each UI state attribute are mounted. For example, a searchBox widget is necessary to provide a query.

The uiState passed to initialUiState or via routing needs to be nested per index. For example, if you only have a root index called “instant_search”, you should use a value like { instant_search: { query: 'query' } }.

If you want to change, for example, “query into “q” in routing, you need to use the stateMapping functions to:

• first, in stateToRoute, return an object containing “q” for the query,
• then, in routeToState, replace that “q” again with “query”.

If you want to group, for example, “turquoise”, “ocean” and “sky” under “blue”, the recommended solution is to group them at indexing time. You can either add the group name as a separate attribute to globally filter on, or add both values in an array to make both the group and the individual value show up in the list.

For example, with the following dataset:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[
  {
    "objectID": "1",
    "color": "turquoise"
  },
  {
    "objectID": "2",
    "color": "ocean"
  },
  {
    "objectID": "3",
    "color": "sky"
  }
]

You could create an additional attribute and use it for faceting:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
[
  {
    "objectID": "1",
    "color": "turquoise",
    "colorGroup": "blue"
  },
  {
    "objectID": "2",
    "color": "ocean",
    "colorGroup": "blue"
  },
  {
    "objectID": "3",
    "color": "sky",
    "colorGroup": "blue"
  }
]

Or you could list the individual colors and their groups so you can use them both for faceting:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
[
  {
    "objectID": "1",
    "color": [
      "turquoise",
      "blue"
    ]
  },
  {
    "objectID": "2",
    "color": [
      "ocean",
      "blue"
    ]
  },
  {
    "objectID": "3",
    "color": [
      "sky",
      "blue"
    ]
  }
]

A refinementList widget displays the most common values for each facet. Sometimes you might have thousands of different values, and it would be impossible to display them all on the UI. You can make the widget searchable to search for more values based on the user’s query.

Each search query might have different common facet values. What’s visible in the refinement widget depends on which facet values are common for that search query. It can happen that you select a facet value for one search, change the search query, and the selected facet value disappears. It might be a rare facet value for the new search query. The refinement is still active, but it’s not shown in the user interface. This can be confusing.

To also show uncommon facet values, ensure that the maximum number of facet values are returned, by using the configure widget. This gives the widget more data to match its refined values with those returned by Algolia. It has no any incidence on the number of items shown—the boundaries set by limit and showMoreLimit still apply.

1
2
3
4
5
6
search.addWidgets([
  // ...
  configure({
    maxValuesPerFacet: 1000,
  }),
]);

If you enable InstantSearch routing, only the parameters coming from widgets are included in the URL. To keep other parameters unrelated to InstantSearch, add them when implementing createURL.

For example, to keep all URL parameters that start with “utm_”, use the following code:

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
history({
  // ... other options
  parseURL({ qsModule, location }) {
    return qsModule.parse(location.search.slice(1));
  },
  createURL({ qsModule, location, routeState }) {
    const { origin, pathname, hash } = location;

    const queriesFromUrl = qsModule.parse(location.search.slice(1));

    // Get all parameters from the URL that are not in the InstantSearch state and that start with "utm_"
    const utmQueries = Object.fromEntries(
      Object.entries(queriesFromUrl).filter(
        ([key]) =>
          !Object.keys(routeState).includes(key) &&
          // Add here a condition to keep the parameters you want, for example starting with "utm_"
          key.startsWith('utm_')
      )
    );

    // Create query string with InstantSearch state and other parameters
    const queryString = qsModule.stringify(
      {
        ...routeState,
        ...utmQueries,
      },
      {
        addQueryPrefix: true,
        arrayFormat: 'repeat',
      }
    );

    return `${origin}${pathname}${queryString}${hash}`;
  },
});

When the search result is the same, some components (templates) may skip re-render.

You can use a panel widget to access the results, and use the hidden function to hide a refinement based on how many facet values it has:

1
2
3
4
5
6
7
8
9
instantsearch.widgets.panel({
  hidden(options) {
    const facetValues = options.results.getFacetValues('brand');
    return Array.isArray(facetValues) ? facetValues.length <= 1 : false;
  },
})(instantsearch.widgets.refinementList)({
  container: '#brand-list',
  attribute: 'brand',
})

When the dynamicWidgets receives results, it mounts the chosen widgets for that result. An initial search does two network requests. This is because adding a new widget requires a new network request, to know what the refinements are for a facet.

You can avoid this by forcing all facets to be returned by Algolia, or all facets that you maximally want to display the results of. This can be done by adding facets: ['*'] and maxValuesPerFacet using a configure widget:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
search.addWidgets([
  instantsearch.widgets.configure({
    facets: ['*'],
    // the highest value you could mount in "limit"
    maxValuesPerFacet: 10,
  }),
  instantsearch.widgets.dynamicWidgets({
    container: '#dynamic-widgets',
    fallbackWidget: ({ container, attribute }) =>
      instantsearch.widgets.menu({ container, attribute, limit: 10 }),
    widgets: [
      container =>
        instantsearch.widgets.hierarchicalMenu({
          limit: 10,
          attributes: [
            'hierarchicalCategories.lvl0',
            'hierarchicalCategories.lvl1',
          ],
        }),
    ],
  }),
]);

When the dynamicWidgets receives results, it mounts the chosen widgets for that result. To avoid doing an extra network request, facets is set to ['*'] by default.

If you prefer to do two network requests with only the relevant facets returned, you can set facets to [] like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
search.addWidgets([
  instantsearch.widgets.dynamicWidgets({
    container: '#dynamic-widgets',
    facets: [],
    fallbackWidget: ({ container, attribute }) =>
      instantsearch.widgets.menu({ container, attribute, limit: 10 }),
    widgets: [
      container =>
        instantsearch.widgets.hierarchicalMenu({
          limit: 10,
          attributes: [
            'hierarchicalCategories.lvl0',
            'hierarchicalCategories.lvl1',
          ],
        }),
    ],
  }),
]);

More detail on these approaches can be found in the facet display guide.

Dynamic widgets can show up to 1,000 facets. However, if you do have more than 1,000 facets, here’s how to display the ones with the most results.

1. Add an applicable_facets facet to every object:

1
2
3
4
5
  {
    "applicable_facets": ["special_type", "color"],
    "special_type": "stretch",
    "color": "blue"
  }

1. Configure the dynamic widget so it doesn’t ask for all facets. Many of them will be hidden anyway because of the 1,000 facet limit. To do this, set facets to [] (empty).

1
2
3
  dynamicWidgets({
    facets: []
  })

1. Ensure that applicable_facets is always requested. Such as from a hidden menu:

1
  connectMenu(() => {})({ attribute: "applicable_facets" })

1. use transformItems of dynamicWidgets to use the “applicable_facets” for dynamic widget rendering:

1
2
3
4
5
6
  dynamicWidgets({
    facets: [],
    transformItems(_items, { results }) {
      return Object.keys(results._rawResults[0].facets.applicable_facets);
    }
  });