Guides / Building Search UI / UI & UX patterns

Jul 16, 2024

Facet display in InstantSearch iOS

As of May 1st, 2024, Apple requires all iOS apps to include a privacy manifest. Ensure you incorporate our provided privacy manifest files into your documentation. For more details, see Privacy Manifest.

Configure the attributes to use for faceting on your search index.
Configure your facet display.
Build a UI capable of interpreting the renderingContent setting. For this step, use InstantSearch library widgets. You can create a UI with other tools but must write the interpretation logic yourself.

Select the Search product icon on your dashboard and then select your index.
Click the Configuration tab.
Under the Filtering and Faceting category, click Facet display.
Click Add facet to display to choose the facets you want to display in your UI.
Use the = icon next to each facet to drag them into the correct position. The order you set here determines how facets display in your UI.
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 to display them first.
- Hide some values from the list entirely.
- Choose how to display the remaining facet values: by count, alphabetically, or only display pinned values.
To remove a facet from the list and stop displaying it in your UI, click the trash icon.
Save your changes.

If you want to only display the facets “brand”, “size”, and “color” in your UI, declare than as attributes for faceting and add them to the list of facets to display.

With those three facets added, you want to display the brands alphabetically. However:

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 other 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 you want a more dynamic approach that customizes the display of the facets and values for a specific query or category, see the Merchandising facets.

To replicate the preceding dashboard example, use the API client’s setSettings method with the following settings applied to your index:

Copy

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
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))
}

Hiding facet values is not supported in InstantSearch iOS and InstantSearch Android.

The following example shows three facets: author, brand, and on_sale (in that order). The author facet is sorted by number of hits, the brand facet is ordered alphabetically, always shows the facet value “Kensington” in the first position (pinned) and never shows the value “Bosch” (hidden). The on_sale facet only shows the pinned true value.

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
index
  .setSettings({
    renderingContent: {
      facetOrdering: {
        facets: {
          order: ['author', 'brand', 'on_sale'],
        },
        values: {
          "author": {
            "sortRemainingBy": "count"
          },
          "brand": {
            "order": ["Kensington"],
            "hide": ["Bosch"]
            "sortRemainingBy": "alpha"
          },
          "on_sale": {
            "order": ["true"],
            "sortRemainingBy": "hidden"
          },
        },
      },
    },
  })
  .then(() => {
    // done
  });

Build the UI with InstantSearch

The simplest way to control facet display is to use InstantSearch. This UI library has built-in widgets that understand the renderingContent data returned by searches. This data includes everything you need to show facets how you want.

To 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 or set facetOrdering to true.

Copy

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>

Upgrade InstantSearch

If you already built your UI using InstantSearch, you may need to update it to use the dynamic widgets introduced in 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.

With dynamicWidgets, Algolia automatically mounts the appropriate widgets for the search results. By default, dynamic widgets request all facets and generate an extra network request for this. To avoid this, add the facets: [] option:

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

Build the UI without InstantSearch

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

Interpret the renderingContent parameter returned along search results,
Order 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

If you hardcode the list of facets to display on a page, you 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 loop over to display individual facet lists.

You need to list the attribute you want to display facets of in searchParameters.facets. Read the possible results from result.facets[facetName]. After fetching those values, you can read the result.renderingContent.facetOrdering.values[facetName] object to sort them. This object has the following keys:

order: an array of facet values to pin at the start of the list
hide: an array of facet values to hide from the list
sortRemainingBy: 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 only displays the ordered items.

Redirects

Voice search

Did you find this page helpful?

Facet display in InstantSearch iOS

On this page

Manage facet display from the Algolia dashboard

Configure facet display from the dashboard

Configure facet display with the API

Hide facet values

Build the UI with InstantSearch

Facet display requirements for InstantSearch

Upgrade InstantSearch

Optimize dynamic widget network requests

Build the UI without InstantSearch

Read the facet order

Read the facet value order

On this page