InstantSearch / React / V6 / API reference

ConfigureRelatedItems | React InstantSearch V6 (Deprecated)

Deprecated content
This documentation is for a deprecated version of React InstantSearch. Some features and settings may be missing or their usage may have changed. Refer to the documentation for the latest version of React InstantSearch for up-to-date information.

Signature

Signature
<ExperimentalConfigureRelatedItems
  hit={object}
  matchingPatterns={object}
  // Optional parameters
  transformSearchParameters={function}
/>

About this widget

This widget is experimental and is subject to change in minor versions.

The ExperimentalConfigureRelatedItems widget computes search parameters to create related items experiences without rendering anything.

The hit passed to the widget is used as a reference to compute the search parameters and retrieve related items.

We recommend that you use this widget in a separate index-widget that you use specifically for related items.

This widget can be used with react-dom and react-native. It doesn’t render anything on screen, it only applies the provided parameters to the search.

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import { ExperimentalConfigureRelatedItems } from 'react-instantsearch-dom';

const hit = {
  objectID: '1234',
  name: 'Remote controller',
  brand: 'Amazon',
  categories: ['TV & Home Theater', 'Streaming Media Players'],
};

<Index indexName="related_items">
  <ExperimentalConfigureRelatedItems
    hit={hit}
    matchingPatterns={{
      brand: { score: 1 },
      categories: { score: 2 }
    }}
  />
  // This displays only related hits
  <Hits />
</Index>

Props

hit

Required
Type: object

The hit passed to the widget and used as a reference to compute the search parameters sent to Algolia.

This hit can be retrieved from any location (the app state, the backend, the history, etc.).

1
2
3
4
5
6
7
8
9
10
11
const hit = {
  objectID: '1234',
  name: 'Remote controller',
  brand: 'Amazon',
  categories: ['TV & Home Theater', 'Streaming Media Players'],
};

<ExperimentalConfigureRelatedItems
  // ...
  hit={hit}
/>

matchingPatterns

Required
Type: object

A schema that creates scored filters based on the hit’s attributes.

In the example below, the brand value gets a score of 1 while the categories value gets a score of 2.

The preceding hit would generate the following search parameters:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "sumOrFiltersScores": true,
  "facetFilters": ["objectID:-1234"],
  "optionalFilters": [
    ["brand:Amazon<score=1>"],
    [
      [
        "categories:TV & Home Theater<score=2>",
        "categories:Streaming Media Players<score=2>"
      ]
    ]
  ]
}

You can use nested attributes by using the dot notation to score them: { 'hierarchicalCategories.lvl0': { score: 2 } }.

1
2
3
4
5
6
7
<ExperimentalConfigureRelatedItems
  // ...
  matchingPatterns={{
    brand: { score: 1 },
    categories: { score: 2 }
  }}
/>

transformSearchParameters

Optional
Type: function

Transforms the generated search parameters.

This can be useful to override default parameters or to increase chances of finding related items. A recommended pattern is to consider the words of a hit’s name as optionalWords.

1
2
3
4
5
6
7
8
9
10
<ExperimentalConfigureRelatedItems
  // ...
  transformSearchParameters={searchParameters => {
    return {
      ...searchParameters,
      // Replace `name` by what describes your hit the most
      optionalWords: hit.name.split(' '),
    };
  }}
/>
Did you find this page helpful?