InstantSearch doesn’t provide a built-in option to automatically reset refinements when the query changes. This behavior requires a custom implementation using InstantSearch’s UI state management.
This article describes one possible approach using the onStateChange function, which runs whenever the UI state changes. You can use it to detect query changes and reset refinements accordingly.
High-level approach
1. Listen to UI state updates
Use the onStateChange parameter on the InstantSearch instance to react to UI state changes.
2. Compare the previous and next query values
Check whether the query has changed compared to the previous UI state. The current query is available on the UI state object.
Note that UI state is scoped per index. You can refer to an example UI state object here.
3. Reset the rest of the state when the query changes
When a query change is detected, update the UI state so that:
The new query value is preserved
Refinements (facet filters, toggles, numeric ranges, etc.) are removed
Any other state you don’t want to persist is cleared
The exact shape of the state you keep or remove depends on your use case.
Important considerations
This is a custom pattern
InstantSearch does not recommend or enforce a single way to reset state. You are responsible for deciding which parts of the UI state should persist.UI state is index-scoped
Refinements live under the index key in the UI state. Clearing refinements typically means replacing that index’s state with a minimal object.Routing and URLs
If you use custom state mapping for your URLs, ensure your state updates remain consistent with your routing configuration, especially when refinements are added or removed.
If instead you need a user-triggered way to clear all refinements, you can use the clearRefinements widget.