make it a flag

src/lib/InstantSearch.ts

@@ -139,6 +139,17 @@ export type InstantSearchOptions<
    * @deprecated This property will be still supported in 4.x releases, but not further. It is replaced by the `insights` middleware. For more information, visit https://www.algolia.com/doc/guides/getting-insights-and-analytics/search-analytics/click-through-and-conversions/how-to/send-click-and-conversion-events-with-instantsearch/js/
    */
   insightsClient?: AlgoliaInsightsClient;
+
+  /**
+   * Changes the way `dispose` is used in InstantSearch lifecycle.
+   *
+   * If the existing default (searchParameters) is used, each widget unmounting will remove its state as well, even if there are multiple widgets reading that UI State.
+   *
+   * With the future default (uiState), each widget unmounting will only remove its own state if it's the last of its type. This allows for dynamically adding and removing widgets without losing the state of those widgets.
+   *
+   * @default 'searchParameters'
+   */
+  disposeMode?: 'searchParameters' | 'uiState';
 };
 
 export type InstantSearchStatus = 'idle' | 'loading' | 'stalled' | 'error';
@@ -185,6 +196,10 @@ class InstantSearch<
    */
   public error: Error | undefined = undefined;
 
+  public flags: {
+    disposeMode: InstantSearchOptions['disposeMode'];
+  };
+
   /**
    * @deprecated use `status === 'stalled'` instead
    */
@@ -212,8 +227,13 @@ Use \`InstantSearch.status === "stalled"\` instead.`
       searchClient = null,
       insightsClient = null,
       onStateChange = null,
+      disposeMode = 'searchParameters',
     } = options;
 
+    this.flags = {
+      disposeMode,
+    };
+
     if (indexName === null) {
       throw new Error(withUsage('The `indexName` option is required.'));
     }

src/widgets/index/index.ts

@@ -347,20 +347,29 @@ const index = (widgetParams: IndexWidgetParams): IndexWidget => {
       );
 
       if (localInstantSearchInstance && Boolean(widgets.length)) {
-        widgets.forEach((widget) => {
-          // doing nothing with the return value of dispose, this is handled by the next part
-          widget.dispose!({
-            helper: helper!,
-            state: helper!.state,
-            parent: this,
+        let initialSearchParameters;
+        if (
+          localInstantSearchInstance.flags.disposeMode === 'searchParameters'
+        ) {
+          initialSearchParameters = widgets.reduce((state, widget) => {
+            // the `dispose` method exists at this point we already assert it
+            const next = widget.dispose!({
+              helper: helper!,
+              state,
+              parent: this,
+            });
+
+            return next || state;
+          }, helper!.state);
+        } else {
+          initialSearchParameters = new algoliasearchHelper.SearchParameters({
+            index: this.getIndexName(),
           });
-        });
+        }
 
         const newState = getLocalWidgetsSearchParameters(localWidgets, {
           uiState: localUiState,
-          initialSearchParameters: new algoliasearchHelper.SearchParameters({
-            index: this.getIndexName(),
-          }),
+          initialSearchParameters,
         });
 
         localUiState = getLocalWidgetsUiState(localWidgets, {

test/mock/createInstantSearch.ts

@@ -67,6 +67,9 @@ export const createInstantSearch = (
     emit: jest.fn(),
     listenerCount: jest.fn(),
     sendEventToInsights: jest.fn(),
+    flags: {
+      disposeMode: 'searchParameters',
+    },
     ...args,
   };
 };