🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
UI libraries / InstantSearch.js / Widgets

configureRelatedItems

Signature 
EXPERIMENTAL_configureRelatedItems(
  hit: object
  matchingPatterns: object
  // Optional parameters
  transformSearchParameters: function
);
Import
Copy 
1

import { EXPERIMENTAL_configureRelatedItems } from 'instantsearch.js/es/widgets';
See code examples
See live example

About this widget

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

The EXPERIMENTAL_configureRelatedItems 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.

Examples

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

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

search.addWidgets([
  // Add widgets in the main index
  // ...

  index({ indexName: 'related_items' }).addWidgets([
    EXPERIMENTAL_configureRelatedItems({
      hit,
      matchingPatterns: {
        brand: { score: 1 },
        categories: { score: 2 }
      }
    });
    // This displays only related hits
    hits(),
  ]),
]);

Options

Parameter Description
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'],
};

EXPERIMENTAL_configureRelatedItems({
  // ...
  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

EXPERIMENTAL_configureRelatedItems({
  // ...
  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

EXPERIMENTAL_configureRelatedItems({
  // ...
  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.

Customize the UI with connectConfigureRelatedItems

If you want to create your own UI of the configureRelatedItems widget, you can use connectors.

This connector is also used to build other widgets: Configure

To use connectConfigureRelatedItems, you can import it with the declaration relevant to how you installed InstantSearch.js.

Copy 
1

import { connectConfigureRelatedItems } from 'instantsearch.js/es/connectors';

Then it’s a 3-step process:

// 1. Create a render function
const renderConfigureRelatedItems = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const customConfigureRelatedItems = EXPERIMENTAL_connectConfigureRelatedItems(
  renderConfigureRelatedItems
);

// 3. Instantiate
search.addWidgets([
  customConfigureRelatedItems({
    // instance params
  })
]);

See code examples

Create a render function

This rendering function is called before the first search (init lifecycle step) and each time results come back from Algolia (render lifecycle step).

const renderConfigureRelatedItems = (renderOptions, isFirstRender) => {
  const {
    function refine,
    object widgetParams,
  } = renderOptions;

  if (isFirstRender) {
    // Do some initial rendering and bind events
  }

  // Render the widget
}

Rendering options

Parameter Description
refine
type: function

Removes the generated searchParameters and applies the provided ones.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

const renderConfigureRelatedItems = (renderOptions, isFirstRender) => {
  const { refine, widgetParams } = renderOptions;

  if (isFirstRender) {
    const button = document.createElement('button');
    button.textContent = 'Sets "hitsPerPage" to 10';

    button.addEventListener('click', () => {
      refine({ ...widgetParams.searchParameters, hitsPerPage: 10 });
    });

    document.querySelector('#configure-related-items').appendChild(button);
  }
};
widgetParams
type: object

All original widget options forwarded to the render function.

The generated searchParameters are injected in widgetParams.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

const renderConfigureRelatedItems = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;

  widgetParams.container.innerHTML = `
    <pre>${JSON.stringify(widgetParams.searchParameters, null, 2)}</pre>
  `;
};

// ...

search.addWidgets([
  customConfigureRelatedItems({
    container: document.querySelector('#configure-related-items'),
  })
]);

Create and instantiate the custom widget

We first create custom widgets from our rendering function, then we instantiate them. When doing that, there are two types of parameters you can give:

  • Instance parameters: they are predefined parameters that you can use to configure the behavior of Algolia.
  • Your own parameters: to make the custom widget generic.

Both instance and custom parameters are available in connector.widgetParams, inside the renderFunction.

const customConfigureRelatedItems = EXPERIMENTAL_connectConfigureRelatedItems(
  renderConfigureRelatedItems
);

search.addWidgets([
  customConfigureRelatedItems({
    hit: object,
    matchingPatterns: object,
    transformSearchParameters: function,
  })
]);

Instance options

Parameter Description
hit
type: object
Required

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

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'],
};

customConfigureRelatedItems({
  // ...
  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 values gets a score of 2.

The hit above 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

customConfigureRelatedItems({
  // ...
  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

customConfigureRelatedItems({
  // ...
  transformSearchParameters(searchParameters) {
    return {
      ...searchParameters,
      // Replace `name` by what describes the most your hit
      optionalWords: hit.name.split(' '),
    };
  }
});

Full example

Copy 
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

// Create the render function
const renderConfigureRelatedItems = (renderOptions, isFirstRender) => {
  const { refine, widgetParams } = renderOptions;

  if (isFirstRender) {
    const button = document.createElement('button');
    button.textContent = 'Sets "hitsPerPage" to 10';

    button.addEventListener('click', () => {
      refine({ ...widgetParams.searchParameters, hitsPerPage: 10 });
    });

    document.querySelector('#configure-related-items').appendChild(button);
  }
};

// Create the custom widget
const customConfigureRelatedItems = EXPERIMENTAL_connectConfigureRelatedItems(
  renderConfigureRelatedItems
);

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

search.addWidgets([
  // Add widgets in the main index
  // ...

  index({ indexName: 'related_items' }).addWidgets([
    customConfigureRelatedItems({
      container: document.querySelector('#configure-related-items'),
      hit,
      matchingPatterns: {
        brand: { score: 1 },
        categories: { score: 2 }
      }
    }),
    hits(),
  ]),
]);
Did you find this page helpful?
InstantSearch.js v4