API Reference / InstantSearch.js / configureRelatedItems

configureRelatedItems

A
Signature 
instantsearch.widgets.EXPERIMENTAL_configureRelatedItems(
  hit: object
  matchingPatterns: object
  // Optional parameters
  transformSearchParameters: function
);
See code examples
See live example

About this widget # A

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

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

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

Options # A

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

instantsearch.widgets.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

instantsearch.widgets.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

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

HTML output# A

This widget has no HTML output.

Customize the UI with connectConfigureRelatedItems# A

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

It’s a 3-step process:

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

// 2. Create the custom widget
const customConfigureRelatedItems = instantsearch.connectors.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 #

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 = instantsearch.connectors.EXPERIMENTAL_connectConfigureRelatedItems(
  renderConfigureRelatedItems
);

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

Instance options #

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 = instantsearch.connectors.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
  // ...

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