Guides / Building Search UI / UI & UX patterns / Facet Display

Building a UI for Facet Display

This guide describes how to build a UI that enables you to control the display of facets and their values directly from the Algolia dashboard. This enables you to control the default order of facets and their values, as well as merchandising them from the Visual Editor.

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 leverage 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.25.0
  • Vue InstantSearch : available from version 3.8.1
  • React InstantSearch : available from version 6.12.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.

This default implementation leads to one extra search request to retrieve the values only for the relevant facets. You can avoid the extra request as described in the next section.

Preventing extra search request

When the dynamicWidgets receives results, it mounts the chosen widgets for that result. An initial search does two network requests. This is because adding a new widget requires a new network request, to know what the refinements are for a facet.

You can avoid this by forcing all facets to be returned by Algolia, or even all facets that you maximally want to display the results of. You can force all facets to be returned by Algolia by creating a proxy of the search client as in the conditional requests guide.

const searchClient = algoliasearch('YourApplicationID', 'YourAPIKey');

const search =; = function(queries) {
  // request all facets
  queries[0].params.facets = '*';

  return search(queries);

Building the UI without InstantSearch

If you aren’t using InstantSearch to build your UI, you need to build within your front end 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.

There are two steps to the custom implementation of front-end search:

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.

Did you find this page helpful?