API Reference / React InstantSearch / ConfigureRelatedItems

ConfigureRelatedItems

Signature 
<ExperimentalConfigureRelatedItems
  hit={object}
  matchingPatterns={object}
  // Optional parameters
  transformSearchParameters={function}
/>
See code examples
See live example

About this widget

We released React InstantSearch Hooks, a new InstantSearch library for React. We recommend using React InstantSearch Hooks in new projects or upgrading from React InstantSearch.

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 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

Copy 
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
type: object
Required

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.).
Copy 
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
type: object
Required

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:

Copy 
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 } }.
Copy 
1
2
3
4
5
6
7

<ExperimentalConfigureRelatedItems
  // ...
  matchingPatterns={{
    brand: { score: 1 },
    categories: { score: 2 }
  }}
/>
transformSearchParameters
type: function
Optional

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.
Copy 
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(' '),
    };
  }}
/>

HTML output

This widget has no HTML output.

Did you find this page helpful?
React InstantSearch v6