Turn off Automatic Filtering and Boosting with InstantSearch.js

Controlling Automatic Filtering and Boosting in your UI

If you want to have Automatic Filtering and Boosting on or off for all searches, you only need to enable the feature to filter the results automatically.

If you want to let users turn Automatic Filtering and Boosting on or off, you can build an InstantSearch widget. This widget should inform users that the results are filtered. The widget should also let users remove any applied filters.

There are three steps to building an Automatic Filtering and Boosting widget:

Check the search response. The search response includes the following properties if Automatic Filtering and Boosting is enabled:

Copy
 {
   "extensions": {
     "queryCategorization": {
       "autofiltering": {
         "facetFilters": [],
         "optionalFilters": []
       }
     }
   }
 }

If filters are applied to the query, they’re listed in the facetFilters property.

Copy
 {
   "facetFilters": [
     "category.level0:Fresh products",
     "category.level1:Fresh vegetables",
     "category.level2:Tomatoes"
   ]
 }

Let users remove applied filters. To remove filters applied with Automatic Filtering and Boosting, you need to turn the feature off for the current query using the enableAutoFiltering API parameter.

Copy
 {
   "extensions": {
     "queryCategorization": {
       "enableAutoFiltering": false
     }
   }
 }

Turn on Automatic Filtering and Boosting for new queries. To keep Automatic Filtering and Boosting for other queries, you must first check for a query change and then set enableAutoFiltering to true.

The following custom connector implements all steps to let users turn off Automatic Filtering and Boosting for a search query.

The connector requires the Algolia search helper.

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
//connectAutoFiltering.js

// util function to set the query parameter (step 2)
function setAutoFiltering(value, helper) {
  return helper.setQueryParameter('extensions', {
    queryCategorization: {
      enableAutoFiltering: value,
    },
  });
}

export function connectAutoFiltering(renderFn, unmountFn = () => {}) {
  return function autoFiltering(widgetParams) {
    const connectorState = {};
    return {
      $$type: 'algolia.beta.autoFiltering',

      init(initOptions) {
        const { instantSearchInstance } = initOptions;

        renderFn(
          {
            ...this.getWidgetRenderState(initOptions),
            instantSearchInstance,
          },
          true
        );
      },

      render(renderOptions) {
        const { instantSearchInstance } = renderOptions;

        renderFn(
          {
            ...this.getWidgetRenderState(renderOptions),
            instantSearchInstance,
          },
          false
        );
      },

      dispose() {
        unmountFn();
      },

      getWidgetSearchParameters(searchParameters) {
        return searchParameters;
      },

      getRenderState(renderState, renderOptions) {
        return {
          ...renderState,
          autoFiltering: this.getWidgetRenderState(renderOptions),
        };
      },

      // this is where the logic happens
      getWidgetRenderState({ results, helper, state }) {
        if (!connectorState.cancelAutoFiltering) {
          // exposing a function to disable autofiltering
          connectorState.cancelAutoFiltering = () => {
            // Disable auto filtering for next search
            setAutoFiltering(false, helper);
            helper.search();

            // storing in the state the disabled query
            connectorState.disabledQuery = helper.getQuery().query;
          };
        }

        // empty results case
        if (!results) {
          return {
            appliedFilters: [],
            cancelAutoFiltering: () => {},
            widgetParams,
          };
        }

        // enabling back auto filtering if the query has changed (step 3)
        if (
          // "state" stores the current query parameters
          state.extensions &&
          state.extensions.queryCategorization.enableAutoFiltering === false &&
          connectorState.disabledQuery &&
          results.query !== connectorState.disabledQuery
        ) {
          setAutoFiltering(true, helper);

          if (
            results.extensions &&
            results.extensions.queryCategorization.normalizedQuery
          ) {
            // if the current query has predicted categories, we refine the search with autofiltering enabled

            helper.search();
          }
        }

        // Retrieving the applied filters (step 1)
        const facetFilters =
          (results.extensions &&
            results.extensions.queryCategorization.autofiltering &&
            results.extensions.queryCategorization.autofiltering
              .facetFilters) ||
          [];

        return {
          appliedFilters:
            facetFilters.map((facetFilter) => ({
              name: facetFilter.split(':')[0],
              value: facetFilter.split(':')[1],
            })),
          cancelAutoFiltering: connectorState.cancelAutoFiltering,
          widgetParams,
        };
      },
    };
  };
}

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
// connectAutoFiltering.ts
import type { Connector } from 'instantsearch.js';

export type AutoFilteringConnectorParams = {};

export type AutoFilteringRenderState = {
  appliedFilters: Array<{
    name: string;
    value: string;
  }>;
  cancelAutoFiltering(): void;
};

export type AutoFilteringWidgetDescription = {
  $$type: 'algolia.beta.autoFiltering';
  renderState: AutoFilteringRenderState;
  indexRenderState: {};
  indexUiState: {};
};

type AutoFilteringConnector = Connector<
  AutoFilteringWidgetDescription,
  AutoFilteringConnectorParams
>;

type ConnectorState = {
  disabledQuery?: string;
  cancelAutoFiltering?: AutoFilteringRenderState['cancelAutoFiltering'];
};

// util function to set the query parameter (step 2)
function setAutoFiltering(value, helper) {
  return helper.setQueryParameter('extensions', {
    queryCategorization: {
      enableAutoFiltering: value,
    },
  });
}

type WidgetRenderStateWithResultsExtensions = Parameters<
  ReturnType<ReturnType<AutoFilteringConnector>>['getWidgetRenderState']
>[0] & {
  state: {
    extensions?: {
      queryCategorization?: {
        enableAutoFiltering?: boolean;
      };
    };
  };
  results: {
    extensions?: {
      queryCategorization?: {
        normalizedQuery?: string;
        autofiltering?: {
          facetFilters?: string[];
        };
      };
    };
  };
};

export const connectAutoFiltering: AutoFilteringConnector = (
  renderFn,
  unmountFn = () => {}
) => {
  return function autoFiltering(widgetParams) {
    const connectorState: ConnectorState = {};
    return {
      $$type: 'algolia.beta.autoFiltering',

      init(initOptions) {
        const { instantSearchInstance } = initOptions;

        renderFn(
          {
            ...this.getWidgetRenderState(initOptions),
            instantSearchInstance,
          },
          true
        );
      },

      render(renderOptions) {
        const { instantSearchInstance } = renderOptions;

        renderFn(
          {
            ...this.getWidgetRenderState(renderOptions),
            instantSearchInstance,
          },
          false
        );
      },

      dispose() {
        unmountFn();
      },

      getWidgetUiState(uiState) {
        return uiState;
      },

      getWidgetSearchParameters(searchParameters) {
        return setAutoFiltering(true, searchParameters);
      },

      getRenderState(renderState, renderOptions) {
        return {
          ...renderState,
          autoFiltering: this.getWidgetRenderState(renderOptions),
        };
      },

      // this is where the logic happens
      getWidgetRenderState({
        results,
        helper,
        state,
      }: WidgetRenderStateWithResultsExtensions) {
        if (!connectorState.cancelAutoFiltering) {
          connectorState.cancelAutoFiltering = () => {
            // Disable auto filtering for next search
            setAutoFiltering(false, helper);
            helper.search();

            // storing in the state the disabled query
            connectorState.disabledQuery = helper.getQuery().query;
          };
        }

        // empty results case
        if (!results) {
          return {
            appliedFilters: [],
            cancelAutoFiltering: () => {},
            widgetParams,
          };
        }

        // enabling back auto filtering if the query has changed (step 3)
        if (
          // "state" stores the current query parameters
          state.extensions?.queryCategorization?.enableAutoFiltering ===
            false &&
          connectorState.disabledQuery &&
          results.query !== connectorState.disabledQuery
        ) {
          setAutoFiltering(true, helper);

          if (results.extensions.queryCategorization.normalizedQuery) {
            // if the current query has predicted categories, we refine the search with autofiltering enabled
            helper.search();
          }
        }

        // Retrieving the applied filters (step 1)
        const facetFilters = results.extensions?.queryCategorization?.autofiltering
    ?.facetFilters || [];

        return {
          appliedFilters:
            facetFilters.map((facetFilter) => ({
              name: facetFilter.split(':')[0],
              value: facetFilter.split(':')[1],
            })),
          cancelAutoFiltering: connectorState.cancelAutoFiltering,
          widgetParams,
        };
      },
    };
  };
};

Use this InstantSearch connector to create a widget.

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
// autofiltering.js
import { connectAutoFiltering } from './connectAutoFiltering';

export function autoFiltering(widgetParams) {
  const { container: containerSelector } = widgetParams;

  if (!containerSelector) {
    console.error('The `container` option is required.');
  }

  const container = document.querySelector(containerSelector);

  // the widget render function
  const renderer = (renderOptions, isFirstRender) => {
    const { appliedFilters, cancelAutoFiltering } = renderOptions;

    /**
    * Here we choose to display the applied filters in a banner with a button to disable autofiltering
    * We are displaying only the last filter of the hierarchy, but you can chose to display all of them if you want to
    * It is entirely up to you how you choose to render the filters
    */

    container.innerHTML = appliedFilters.length
      ? `
      <div style="border: 1px solid lightgray; border-radius: 4px; margin: 1rem 0; padding: 1rem;">
        <span><strong>Applied filter:</strong></span>
          <span>${appliedFilters.pop().value}</span>
          <button>&times;</button>
        
      </div>
    `
      : '';

    const button = container.querySelector('button');
    if (button) {
      // attaching our cancel function to our button
      button.addEventListener('click', () => {
        cancelAutoFiltering();
      });
    }
  };

  const makeWidget = connectAutoFiltering(renderer, () => {
    container.innerHTML = '';
  });

  return {
    ...makeWidget({}),
    $$widgetType: 'algolia.beta.autoFiltering',
  };
}

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
// autofiltering.ts
import { connectAutoFiltering } from './connectAutoFiltering';
import type { AutoFilteringRenderState } from './connectAutoFiltering';

type WidgetParams = {
  container: string;
};

export function autoFiltering(widgetParams: WidgetParams) {
  const { container: containerSelector } = widgetParams;

  if (!containerSelector) {
    console.error('The `container` option is required.');
  }

  const container = document.querySelector(containerSelector);

  // the widget render function
  const renderer = (
    renderOptions: AutoFilteringRenderState,
    isFirstRender: boolean
  ) => {
    const { appliedFilters, cancelAutoFiltering } = renderOptions;

    /**
    * Here we choose to display the applied filters in a banner with a button to disable autofiltering
    * We are displaying only the last filter of the hierarchy, but you can chose to display all of them if you want to
    * It is entirely up to you how you choose to render the filters
    */

    container.innerHTML =
      appliedFilters && appliedFilters.length
        ? `
            <div style="border: 1px solid lightgray; border-radius: 4px; margin: 1rem 0; padding: 1rem;">
              <span><strong>Applied filter:</strong></span>
                <span>${appliedFilters.pop().value}</span>
                <button>&times;</button>
              
            </div>
          `
        : '';

    const button = container.querySelector('button');
    if (button) {
      // attaching our cancel function to our button
      button.addEventListener('click', () => {
        cancelAutoFiltering();
      });
    }
  };

  const makeWidget = connectAutoFiltering(renderer, () => {
    container.innerHTML = '';
  });

  return {
    ...makeWidget({}),
    $$widgetType: 'algolia.beta.autoFiltering',
  };
}

If you copy the code snippets into your implementation, check the widget render function to adapt to your design.

You can add the widget to your UI:

Copy
import { autoFiltering } from './autoFiltering';

// ...

const search = instantsearch({
  indexName,
  searchClient,
});

search.addWidgets([
  // ...
  autoFiltering({
    container: '#autofiltering-container',
  }),
]);

Server-side rendering

UI Design Kit

Did you find this page helpful?

Turn off Automatic Filtering and Boosting with InstantSearch.js

On this page

Controlling Automatic Filtering and Boosting in your UI

Building a widget for Automatic Filtering and Boosting

Implementing the widget

On this page