Facet Display in React InstantSearch

This is the React InstantSearch v7 documentation. React InstantSearch v7 is the latest version of React InstantSearch and the stable version of React InstantSearch Hooks.

If you were using React InstantSearch v6, you can upgrade to v7.

If you were using React InstantSearch Hooks, you can still use the React InstantSearch v7 documentation, but you should check the upgrade guide for necessary changes.

If you want to keep using React InstantSearch v6, you can find the archived documentation.

This guide describes how to configure and order facets and their values using the dashboard and API, as well as how to enable the UI using InstantSearch or using a custom solution.

You can find this feature being described as “facet ordering”, “facet merchandising”, “dynamic widgets” or “dynamic facets”.

Managing facet display from the Algolia dashboard

The ability to control the facets to display and their order works by sending a dedicated renderingContent parameter alongside search results. This setting needs to be interpreted by the UI your users use to interact with the index.

The main implementation steps are:

1. Configuring the attributes to use for faceting on your search index.
2. Configuring your facet display.
3. Building a UI capable of interpreting the renderingContent setting. For this step, you can use the InstantSearch library which has widgets pre-configured. You can also build your UI using any other tools or platform, but you must rebuild the interpretation logic yourself.

Configuring your facet display using the dashboard

1. Select the Search product icon on your dashboard and then select your index.
2. Click the Configuration tab.
3. Under the Filtering and Faceting category, click Facet display.
4. Click on the Add facet to display button to add the facets you want to display in your UI.
5. Use the = icon next to each facet to drag them into the correct position. The facets in your UI are displayed in the same order as the order you define here.

6. For each facet, click the pen icon to configure how the engine should display the facet’s values. You can:

   • Pin some values at the top of the list if you want them to be displayed first.
   • Configure if the remaining values should be ordered by count, alphabetically, or if you want only to display the values pinned.
7. To remove a facet from the list and stop displaying it in your UI, click the trash icon.
8. Save your changes.

Imagine you want to only display the facets “brand”, “size”, and “color” on your UI. The first step is to add those three facets to the list of facets to display. To be displayed in the list, they need to have already been configured as attributes for faceting.

With those three facets added, you want to ensure that users can easily browse through brands by displaying them alphabetically.

• Since you have a specific partnership with the brand “Lacoste”, you want the brand to always display on top.
• Sizes need to be in a specific order: S, M, L, XL. You may have sizes in different formats in your data, but for the sake of clarity, you only want to display those four. You pin them at the top in the correct order and choose not to display subsequent values
• For colors, you want to display them by count and not pin any specific value.

As soon as you save the changes, the UI adapts to this new configuration.

This approach lets you configure a static facet display. If, however, you want a more dynamic approach that customizes the display of the facets and values for a specific query or category, see the facet merchandising guide.

Configuring your facet display using the API

To apply the same configuration as in the preceding example, you need to apply the following settings:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
$index->setSettings([
  'renderingContent' => [
    'facetOrdering' => [
      'facets' => [
        'order' => ['brand', 'size', 'color']
      ],
      'values' => [
        'brand'=> [
          'order' => ['Uniqlo'],
          'sortRemainingBy' => 'alpha'
        ],
        'size'=> [
          'order' => ['S', 'M', 'L','XL'],
          'sortRemainingBy' => 'hidden'
        ],
        'color'=> [
          'sortRemainingBy' => 'count'
        ]
      ]
    ]
  ]
]);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
index.set_settings({
  renderingContent: {
    facetOrdering: {
      facets: {
        order: ['brand', 'size', color]
      },
      values: {
        brand: {
          order: ['Uniqlo'],
          sortRemainingBy: 'alpha'
        },
        size: {
          order: ['S', 'M', 'L'],
          sortRemainingBy: 'hidden'
        },
        color: {
          sortRemainingBy: 'count'
        }
      }
    }
  }
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
index
  .setSettings({
    renderingContent: {
      facetOrdering: {
        facets: {
          order: ['brand', 'size', 'color'],
        },
        values: {
          brand: {
            order: ['Uniqlo'],
            sortRemainingBy: 'alpha',
          },
          size: {
            order: ['S', 'M', 'L', 'XL'],
            sortRemainingBy: 'hidden',
          },
        },
      },
    },
  })
  .then(() => {
    // done
  });

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
index.set_settings({
    'renderingContent': {
        'facetOrdering': {
            'facets': {
                'order': ['brand', 'size', 'color'],
            },
            'values': {
                'brand': {
                    'order': ['Uniqlo'],
                    'sortRemainingBy': 'alpha',
                },
                'size': {
                    'order': ['S', 'M', 'L', 'XL'],
                    'sortRemainingBy': 'hidden',
                },
            },
        },
    },
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
let facetOrdering = FacetOrdering(facets: FacetsOrder(order: ["brand", "size", "color"]),
                                  values: [
                                   "brand": FacetValuesOrder(
                                      order: ["Uniqlo"],
                                      sortRemainingBy: .alpha
                                    ),
                                   "size": FacetValuesOrder(
                                      order: ["S", "M", "L", "XL"],
                                      sortRemainingBy: .hidden
                                    ),
                                   "color": FacetValuesOrder(
                                      sortRemainingBy: .count
                                    )
                                  ])
let renderingContent = RenderingContent(facetOrdering: facetOrdering)
let settings = Settings()
  .set(\.renderingContent, to: renderingContent)

index.setSettings(settings) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
val facetOrdering = FacetOrdering(
    facets = FacetsOrder(order = listOf("brand", "sizer","color")),
    values = mapOf(
        Attribute("brand") to FacetValuesOrder(
            order = listOf("Uniqlo"),
            sortRemainingBy = SortRule.Alpha
        ),
        Attribute("size") to FacetValuesOrder(
            order = listOf("S", "M", "L", "XL"),
            sortRemainingBy = SortRule.Hidden
        ),
        Attribute("color") to FacetValuesOrder(
            sortRemainingBy = SortRule.Count
        )
    )
)
val renderingContent = RenderingContent(facetOrdering)
val settings = Settings(renderingContent = renderingContent)
index.setSettings(settings)

1
Not available for C#.

1
2
3
4
5
6
7
8
9
10
11
FacetsOrder facetsOrder = new FacetsOrder(Arrays.asList("brand", "size", "color"));
Map<String, FacetValuesOrder> values = new LinkedHashMap<>();
values.put("brand", new FacetValuesOrder(Collections.singletonList("Uniqlo"), "alpha"));
values.put("size", new FacetValuesOrder(Arrays.asList("S", "M", "L", "XL"), "hidden"));
values.put("size", new FacetValuesOrder(null, "count"));
FacetOrdering facetOrdering = new FacetOrdering(facetsOrder, values);
RenderingContent renderingContent = new RenderingContent(facetOrdering);
// Synchronous
index.setSettings(new IndexSettings().setRenderingContent(renderingContent));
// Asynchronous
index.setSettingsAsync(new IndexSettings().setRenderingContent(renderingContent));

1
2
3
4
5
6
7
8
9
10
11
var renderingContent = search.RenderingContent{FacetOrdering: &search.FacetOrdering{
  Facets: &search.FacetsOrder{Order: []string{"brand", "size", "color"}},
  Values: map[string]search.FacetValuesOrder{
    "brand": search.NewFacetValuesOrder([]string{"Uniqlo"}, search.Alpha),
    "size":  search.NewFacetValuesOrder([]string{"S", "M", "L", "XL"}, search.Hidden),
    "color": search.NewFacetValuesOrder(null, search.Hidden),
  },
}}
res, err := index.SetSettings(search.Settings{
    RenderingContent: &renderingContent,
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
val facetOrdering = FacetOrdering(
  facets = FacetsOrder(order = Seq("brand", "size", "color")),
  values = Map(
    "brand" -> FacetValuesOrder(
      order = Seq("Uniqlo"),
      sortRemainingBy = Some(SortRule.alpha)
    ),
    "size" -> FacetValuesOrder(
      order = Seq("S", "M", "L", "XL"),
      sortRemainingBy = Some(SortRule.hidden)
    ),
    "color" -> FacetValuesOrder(
      sortRemainingBy = Some(SortRule.count)
    )
  )
)
val renderingContent = RenderingContent(facetOrdering = Some(facetOrdering))
client.execute {
  setSettings of "myIndex" `with` IndexSettings(renderingContent = Some(renderingContent))
}

Building the UI with InstantSearch

The fastest and simplest way to unlock the control of facet display directly from the Algolia dashboard is to build your UI using <InstantSearch>. This library already contains the widgets and logic needed to interpret the renderingContent parameter returned along search results and that contains the facet display information.

Upgrading InstantSearch

If you already built your UI using InstantSearch, you might still need to update it to use the dynamic widgets introduced in the latest versions. The facet display feature is compatible with InstantSearch starting with the following versions:

• InstantSearch.js : available from version 4.22.0
• Vue InstantSearch : available from version 4.1.0
• React InstantSearch : available from version 6.14.0
• InstantSearch iOS : available from version 7.12.0
• InstantSearch Android : available from version 2.11.0

Check the upgrade guide for InstantSearch to upgrade your UI to the latest version.

Using InstantSearch

Once on a compatible version, make your UI compatible with the Facet Display feature:

• Add refinement widgets for the different facets.
• Add a DynamicWidgets container around the widgets you want to sort.
• In those widgets, remove any custom sortBy you have or set facetOrdering to true.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// This example assumes you're including InstantSearch.js in your web
// page via a CDN. If you're using it with a package manager, you
// should adjust the way you import InstantSearch.js and its widgets.
const { dynamicWidgets, menu, hierarchicalMenu } = instantsearch.widgets;

search.addWidgets([
  dynamicWidgets({
    container: '#dynamic-widgets',
    fallbackWidget: ({ container, attribute }) =>
      menu({ container, attribute, limit: 10 }),
    widgets: [
      container =>
        hierarchicalMenu({
          limit: 10,
          attributes: [
            'hierarchicalCategories.lvl0',
            'hierarchicalCategories.lvl1',
          ],
        }),
    ],
  }),
])

1
2
3
4
5
6
7
<DynamicWidgets fallbackComponent={Menu}>
  <RefinementList attribute="brand" />
  <HierarchicalMenu attributes={['hierarchical.lvl0', 'hierarchical.lvl1']} />
  <Panel>
    <Menu attribute="category" />
  </Panel>
</DynamicWidgets>

1
2
3
4
5
6
7
8
9
<ais-dynamic-widgets>
  <ais-refinement-list attribute="brand" />
  <ais-hierarchical-menu
    :attributes="['hierarchical.lvl0', 'hierarchical.lvl1']"
  />
  <ais-panel>
    <ais-menu attribute="category" />
  </ais-panel>
</ais-dynamic-widgets>

Preventing extra data being requested

When dynamicWidgets receives results, it mounts the selected widgets for that result. To avoid an initial search performing two network requests, the default value of dynamic widgets adds facets to ['*'].

You can avoid requesting all facets by making an initial network request. To do this, add facets: [] to dynamic widgets.

You can use this approach if there are many (>100) facet values that you don’t need to display. Instead of requesting all facets with a wildcard (*) only the facets that will be set up in facet ordering are requested.

A downside is that an extra network request happens on mount, so make sure to measure before applying this.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// This example assumes you're including InstantSearch.js in your web
// page via a CDN. If you're using it with a package manager, you
// should adjust the way you import InstantSearch.js and its widgets.
const { dynamicWidgets, menu, hierarchicalMenu } = instantsearch.widgets;

search.addWidgets([
  dynamicWidgets({
    container: '#dynamic-widgets',
    fallbackWidget: ({ container, attribute }) =>
      menu({ container, attribute, limit: 10 }),
    widgets: [
      container =>
        hierarchicalMenu({
          limit: 10,
          attributes: [
            'hierarchicalCategories.lvl0',
            'hierarchicalCategories.lvl1',
          ],
        }),
    ],
    // do two network requests
    facets: []
  }),
])

1
2
3
4
5
6
7
8
9
10
11
<DynamicWidgets
  fallbackComponent={Menu}
  // do two network requests
  facets={[]}
>
  <RefinementList attribute="brand" />
  <HierarchicalMenu attributes={['hierarchical.lvl0', 'hierarchical.lvl1']} />
  <Panel>
    <Menu attribute="category" />
  </Panel>
</DynamicWidgets>

1
2
3
4
5
6
7
8
9
10
<!-- do two network requests -->
<ais-dynamic-widgets :facets="[]">
  <ais-refinement-list attribute="brand" />
  <ais-hierarchical-menu
    :attributes="['hierarchical.lvl0', 'hierarchical.lvl1']"
  />
  <ais-panel>
    <ais-menu attribute="category" />
  </ais-panel>
</ais-dynamic-widgets>

Building the UI without InstantSearch

If you aren’t using InstantSearch to build your UI, you need to build within your frontend the logic to:

• interpret the renderingContent parameter returned along search results,
• and order your facets and values based on your interpretation of the renderingContent parameter values.

A custom implementation of frontend search requires:

• Reading the facet order
• Reading the facet value order

Reading the facet order

If you hard code the list of facets to display on a page, you now can read that from result.renderingContent.facetOrdering.facets.order (all keys are optional). This is the list of attributes that you chose to display, and can be looped over to display individual facet lists.

Reading the facet value order

You still need to list the attribute you want to display facets of in searchParameters.facets, and will also read the possible results from result.facets[facetName]. However the difference now is that after fetching those values, you can read the result.renderingContent.facetOrdering.values[facetName] object to sort those values. This object has the following keys:

• order: this is an array of facet values to pin at the start of the list
• sortRemainingBy: this is a string that describes how to sort the remaining values. Either “alpha” (alphabetically, ascending), “count” (value retrieved from facets[facetName][facetValue], descending) or “hidden”, which means to only display the ordered items.