Skip to main content
Facets allow users to narrow down their search results. For example, when searching for “battery chargers”, if all they want to see are Apple products, they can click the “Apple” refinement. However, users don’t always think about refining their search. They type their queries and don’t always pay attention to filtering options. To manage this and create a better user experience, you can automate facet selection by adding a rule. This rule automatically selects the “Apple” refinement whenever a user types the word “apple”, as in the query “battery chargers apple”. This simplifies the user experience by interpreting what they mean and removing manual steps. Automatic filtering can be surprising to users if they don’t see it. This solution makes the behavior obvious by visually selecting, on screen, the refinement that the rule has automatically selected. Screenshot of an automatically selected facet

​
Before you begin

This tutorial requires InstantSearch.js or React InstantSearch.

​
Implementation guide

This solution follows a two-step process.

​
Create a rule to detect facet values from the query

To filter on the category attribute, you first need to set it in attributesForFaceting. To learn more, see: You can then create your rule: if a user types a term that’s one of the facet values of the category attribute, then automatically filter the query on that value. You can create the rule from the Algolia dashboard or with an API client.

​
With the dashboard

To create this rule in the dashboard, follow these steps:
  1. Go to the Algolia dashboard and select your Algolia application.
  2. On the left sidebar, select Search.
  3. Select your Algolia index and go to the Rules page.
  4. Select Create your first rule or New rule and select Manual Editor.
  5. In the Condition(s) section, click Query contains, search for “categories”, and select {facet:categories}.
  6. In the Consequence(s) section set the following consequence:
    1. Choose Filter/Boost Matching Attributes.
    2. Search for “categories” and select the facet “categories”. It appears as Add Facet “categories”.

​
With an API client

If you are using one of the API clients, you should create the saveRule with the following JSON.
JSON
{
  "conditions": [
    {
      "pattern": "{facet:categories}",
      "anchoring": "contains",
      "alternatives": true
    }
  ],
  "consequence": {
    "params": {
      "automaticFacetFilters": [
        {
          "facet": "categories"
        }
      ]
    },
    "filterPromotes": true
  },
  "enabled": true,
  "objectID": "qr-1595323648567-0"
}

​
Automate refinement selection on the frontend

This solution uses a standard InstantSearch implementation. To automatically select refinements based on a rule, you need to:
  1. Retrieve information from the rule you created earlier to select the refinements.
  2. Automatically select the onscreen refinements.

​
Retrieve active rule information

To retrieve data on the applied rule, you can use the explain query parameter in the configure widget. Sending explain: ['*'] with a query tells the engine to add extra rule details to the explain attribute of the response. These details help to debug or, as here, implement specific frontend logic. 
search.addWidgets([
  // ...
  configure({
    explain: ['*'],
  }),
]);
Here, the API returns information about the rule you created earlier. Later on, you can use this information to decide what refinements to select.
JSON
{
  "explain": {
    "params": {
      "rules": {
        "facetFilters": ["category:groceries"]
      }
    }
  }
}

​
Automatically select the relevant facet

You can automatically select the relevant facets by transforming the items in the refinementList widget. You can retrieve information about the rule-generated facet in the search response and use it to transform the matching item and mark it as refined.
When using React InstantSearch, you can retrieve information about the rule-generated facet in the search response with useInstantSearch(). You can do this in a React component that wraps <RefinementList> and replaces it in your implementation.
search.addWidgets([
  refinementList({
    // ...
    transformItems(items) {
      const facetFilters =
        (search.helper.lastResults.explain &&
          search.helper.lastResults.explain.params.rules.facetFilters) ||
        [];
      return items.map((item) => ({
        ...item,
        isRefined:
          item.isRefined ||
          facetFilters.includes(`categories:${item.value.toLocaleLowerCase()}`),
      }));
    },
  }),
]);

​
See also

⌘I