API Reference / Angular InstantSearch Widgets / ais-configure-related-items

ais-configure-related-items

Widget signature
<ais-experimental-configure-related-items
  [hit]="object"
  [matchingPatterns]="object"
  // Optional parameters
  [transformSearchParameters]="function"
></ais-experimental-configure-related-items>

About this widget

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

The ais-experimental-configure-related-items widget computes search parameters to use in related items experiences, without rendering anything.

The widget uses the hit you pass as a reference to compute relevant search parameters, so you can retrieve related items.

We recommend using this widget in a separate ais-index, used specifically for related items. The ais-index will display the related items.

Examples

1
2
3
4
5
6
7
8
<ais-index index-name="related_items">
  <ais-experimental-configure-related-items
    [hit]="{ objectID: '1234', name: 'Remote controller', brand: 'Amazon', categories: ['TV & Home Theater', 'Streaming Media Players'] }"
    [matchingPatterns]="{ brand: { score: 1 }, categories: { score: 2 } }"
  ></ais-experimental-configure-related-items>
  <!-- This displays only related hits -->
  <ais-hits></ais-hits>
</ais-index>

Props

hit
type: object
Required

The widget uses the hit you pass as a reference to compute the search parameters sent to Algolia.

You can retrieve this hit from anywhere (the app state, the back end, the history, etc.).

1
2
3
4
5
6
<ais-index index-name="related_items">
  <ais-experimental-configure-related-items
    <!-- ... -->
    [hit]="{ objectID: '1234', name: 'Remote controller', brand: 'Amazon', categories: ['TV & Home Theater', 'Streaming Media Players'] }"
  ></ais-experimental-configure-related-items>
</ais-index>
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 hit above 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
<ais-index index-name="related_items">
  <ais-experimental-configure-related-items
    <!-- ... -->
    [matchingPatterns]="{ brand: { score: 1 }, categories: { score: 2 } }"
  ></ais-experimental-configure-related-items>
</ais-index>
transformSearchParameters
type: function
Optional

A function to transform 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
11
12
13
14
15
16
17
18
19
@Component({
   template: `
     <ais-index index-name="related_items">
       <ais-experimental-configure-related-items
         <!-- ... -->
         [transformSearchParameters]="transformSearchParameters"
       />
     </ais-index>
   `,
 })
 export class AppComponent {
   transformSearchParameters(searchParameters) {
     return {
       ...searchParameters,
       // Replace `name` by what describes your hit the most
       optionalWords: this.hit.name.split(' '),
     };
   }
 }

HTML output

This widget has no HTML output.

Did you find this page helpful?