From cfc1710d6d9a6958247d32cc7286649ec1b7bef7 Mon Sep 17 00:00:00 2001
From: Maxime Janton <127086@supinfo.com>
Date: Thu, 12 Oct 2017 11:13:24 +0200
Subject: [PATCH] feat(core): InstantSearch hot remove/add widgets (#2384)

* chore(devnovel): add unmount widgets example
* feat(connectors): implement dispose() API
* feat(widgets): pass `unmountFn` to connectors
* feat(InstantSearch): add `removeWidget()` method
* fix(connectHierarchicalMenu): dont mutate state directly
* feat(dispose): better error message
* refactor(dispose): provide helper state directly
* refactor(widgets): inline disposer fn
* feat(removeWidget): accept array of widgets
* refactor(removeWidget): have two distinct methods
* chore(dev): add `re-mount` button for testing purpose
* feat(addWidget): allow mount widgets after started
* feat(addWidgets): allow mount multiple widgets at once
* test(InstantSearch): removeWidget
* test(instantsearch): removeWidgets()
* test(instantsearch): add widgets after start
* fix(menuSelect): use preact instead of React (#2460)
* fix(test): correctly reset the wired dependency (#2461)
* fix(addWidgets): update helper state before call `init()`
* feat(InstantSearch): add `dispose()` method to remove all widgets
* doc(InstantSearch): add jsdoc for new methods
* doc(custom-widget): add notes about dispose()
* feat(url-sync): implement dispose strategy
* fix(InstantSearch.dispose): dispose urlSyncWidget first
---
 dev/app/index.js                              |   4 +
 dev/app/init-unmount-widgets.js               | 319 ++++++++++++++++++
 docgen/src/guides/custom-widget.md            |  18 +-
 src/connectors/clear-all/connectClearAll.js   |   7 +-
 .../connectCurrentRefinedValues.js            |   7 +-
 .../connectHierarchicalMenu.js                |  19 +-
 .../hits-per-page/connectHitsPerPage.js       |   7 +-
 src/connectors/hits/connectHits.js            |   7 +-
 .../infinite-hits/connectInfiniteHits.js      |   7 +-
 src/connectors/menu/connectMenu.js            |  13 +-
 .../connectNumericRefinementList.js           |   8 +-
 .../connectNumericSelector.js                 |   8 +-
 .../pagination/connectPagination.js           |   7 +-
 .../price-ranges/connectPriceRanges.js        |  13 +-
 src/connectors/range/connectRange.js          |  13 +-
 .../refinement-list/connectRefinementList.js  |  19 +-
 src/connectors/search-box/connectSearchBox.js |   8 +-
 .../sort-by-selector/connectSortBySelector.js |   9 +-
 .../star-rating/connectStarRating.js          |  13 +-
 src/connectors/stats/connectStats.js          |   7 +-
 src/connectors/toggle/connectToggle.js        |  13 +-
 src/lib/InstantSearch.js                      | 122 ++++++-
 src/lib/__tests__/InstantSearch-test.js       | 257 ++++++++++++++
 src/lib/url-sync.js                           |  22 +-
 src/widgets/clear-all/clear-all.js            |   6 +-
 .../current-refined-values.js                 |   5 +-
 .../hierarchical-menu/hierarchical-menu.js    |   7 +-
 .../hits-per-page-selector.js                 |   7 +-
 src/widgets/hits/hits.js                      |   6 +-
 src/widgets/infinite-hits/infinite-hits.js    |   6 +-
 src/widgets/menu/menu.js                      |   6 +-
 .../numeric-refinement-list.js                |   5 +-
 .../numeric-selector/numeric-selector.js      |   7 +-
 src/widgets/pagination/pagination.js          |   6 +-
 src/widgets/price-ranges/price-ranges.js      |   6 +-
 src/widgets/range-slider/range-slider.js      |   6 +-
 .../refinement-list/refinement-list.js        |   6 +-
 src/widgets/search-box/search-box.js          |  11 +-
 .../sort-by-selector/sort-by-selector.js      |   6 +-
 src/widgets/star-rating/star-rating.js        |   6 +-
 src/widgets/stats/stats.js                    |   6 +-
 src/widgets/toggle/toggle.js                  |   6 +-
 42 files changed, 977 insertions(+), 64 deletions(-)
 create mode 100644 dev/app/init-unmount-widgets.js

diff --git a/dev/app/index.js b/dev/app/index.js
index d2e1d0a621..991f647356 100644
--- a/dev/app/index.js
+++ b/dev/app/index.js
@@ -2,6 +2,7 @@ import { registerDisposer, start } from 'dev-novel';
 import initBuiltInWidgets from './builtin/init-stories';
 import initJqueryWidgets from './jquery/init-stories';
 import initVanillaWidgets from './vanilla/init-stories';
+import initUnmountWidgets from './init-unmount-widgets.js';
 
 import '../style.css';
 import '../../src/css/instantsearch.scss';
@@ -21,6 +22,9 @@ switch (true) {
   case q.includes('widgets=jquery'):
     initJqueryWidgets();
     break;
+  case q.includes('widgets=unmount'):
+    initUnmountWidgets();
+    break;
   default:
     initBuiltInWidgets();
 }
diff --git a/dev/app/init-unmount-widgets.js b/dev/app/init-unmount-widgets.js
new file mode 100644
index 0000000000..169503de45
--- /dev/null
+++ b/dev/app/init-unmount-widgets.js
@@ -0,0 +1,319 @@
+/* eslint-disable import/default */
+import { storiesOf } from 'dev-novel';
+import instantsearch from '../../index.js';
+
+import wrapWithHits from './utils/wrap-with-hits.js';
+
+function wrapWithUnmount(getWidget, params) {
+  return wrapWithHits(container => {
+    container.innerHTML = `
+      <div>
+        <div id="widgetContainer"></div>
+        <div style="margin: 10px; border-top: solid 1px #E4E4E4;">
+          <button id="unmount" style="float: left; margin-right: 10px; margin-top: 10px">
+            Unmount widget
+          </div>
+          <button id="remount" style="float: left; margin-right: 10px;">
+            Remount widget
+          </div>
+          <button id="reload" style="float: left;">
+            Reload
+          </div>
+        </div>
+      </div>
+    `;
+
+    const widget = getWidget('#widgetContainer');
+
+    window.search.addWidget(widget);
+
+    function unmount() {
+      window.search.removeWidget(widget);
+      document
+        .getElementById('unmount')
+        .removeEventListener('click', unmount, false);
+    }
+
+    function remount() {
+      window.search.addWidget(widget);
+      document
+        .getElementById('remount')
+        .removeEventListener('click', remount, false);
+    }
+
+    function reload() {
+      window.location.reload();
+      document
+        .getElementById('reload')
+        .removeEventListener('click', reload, false);
+    }
+
+    document
+      .getElementById('unmount')
+      .addEventListener('click', unmount, false);
+
+    document
+      .getElementById('remount')
+      .addEventListener('click', remount, false);
+
+    document.getElementById('reload').addEventListener('click', reload, false);
+  }, params);
+}
+
+export default () => {
+  storiesOf('ClearAll').add(
+    'default',
+    wrapWithUnmount(
+      container => instantsearch.widgets.clearAll({ container }),
+      {
+        searchParameters: {
+          disjunctiveFacetsRefinements: { brand: ['Apple'] },
+          disjunctiveFacets: ['brand'],
+        },
+      }
+    )
+  );
+
+  storiesOf('CurrentRefinedValues').add(
+    'default',
+    wrapWithUnmount(
+      container => instantsearch.widgets.currentRefinedValues({ container }),
+      {
+        searchParameters: {
+          disjunctiveFacetsRefinements: { brand: ['Apple', 'Samsung'] },
+          disjunctiveFacets: ['brand'],
+        },
+      }
+    )
+  );
+
+  storiesOf('HierarchicalMenu').add(
+    'default',
+    wrapWithUnmount(
+      container =>
+        instantsearch.widgets.hierarchicalMenu({
+          container,
+          attributes: [
+            'hierarchicalCategories.lvl0',
+            'hierarchicalCategories.lvl1',
+            'hierarchicalCategories.lvl2',
+          ],
+          rootPath: 'Cameras & Camcorders',
+        }),
+      {
+        searchParameters: {
+          hierarchicalFacetsRefinements: {
+            'hierarchicalCategories.lvl0': [
+              'Cameras & Camcorders > Digital Cameras',
+            ],
+          },
+        },
+      }
+    )
+  );
+
+  storiesOf('Hits').add(
+    'default',
+    wrapWithUnmount(container => instantsearch.widgets.hits({ container }))
+  );
+
+  storiesOf('HitsPerPage').add(
+    'default',
+    wrapWithUnmount(container =>
+      instantsearch.widgets.hitsPerPageSelector({
+        container,
+        items: [
+          { value: 3, label: '3 per page' },
+          { value: 5, label: '5 per page' },
+          { value: 10, label: '10 per page' },
+        ],
+      })
+    )
+  );
+
+  storiesOf('InfiniteHits').add(
+    'default',
+    wrapWithUnmount(container =>
+      instantsearch.widgets.infiniteHits({
+        container,
+        showMoreLabel: 'Show more',
+        templates: {
+          item: '{{name}}',
+        },
+      })
+    )
+  );
+
+  storiesOf('Menu').add(
+    'default',
+    wrapWithUnmount(container =>
+      instantsearch.widgets.menu({
+        container,
+        attributeName: 'categories',
+      })
+    )
+  );
+
+  storiesOf('NumericRefinementList').add(
+    'default',
+    wrapWithUnmount(container =>
+      instantsearch.widgets.numericRefinementList({
+        container,
+        attributeName: 'price',
+        operator: 'or',
+        options: [
+          { name: 'All' },
+          { end: 4, name: 'less than 4' },
+          { start: 4, end: 4, name: '4' },
+          { start: 5, end: 10, name: 'between 5 and 10' },
+          { start: 10, name: 'more than 10' },
+        ],
+        cssClasses: {
+          header: 'facet-title',
+          link: 'facet-value',
+          count: 'facet-count pull-right',
+          active: 'facet-active',
+        },
+        templates: {
+          header: 'Numeric refinement list (price)',
+        },
+      })
+    )
+  );
+
+  storiesOf('NumericSelector').add(
+    'default',
+    wrapWithUnmount(container =>
+      instantsearch.widgets.numericSelector({
+        container,
+        operator: '>=',
+        attributeName: 'popularity',
+        options: [
+          { label: 'Default', value: 0 },
+          { label: 'Top 10', value: 9991 },
+          { label: 'Top 100', value: 9901 },
+          { label: 'Top 500', value: 9501 },
+        ],
+      })
+    )
+  );
+
+  storiesOf('Pagination').add(
+    'default',
+    wrapWithUnmount(container =>
+      instantsearch.widgets.pagination({
+        container,
+        maxPages: 20,
+      })
+    )
+  );
+
+  storiesOf('PriceRanges').add(
+    'default',
+    wrapWithUnmount(container =>
+      instantsearch.widgets.priceRanges({
+        container,
+        attributeName: 'price',
+        templates: {
+          header: 'Price ranges',
+        },
+      })
+    )
+  );
+
+  storiesOf('RefinementList').add(
+    'default',
+    wrapWithUnmount(container =>
+      instantsearch.widgets.refinementList({
+        container,
+        attributeName: 'brand',
+        operator: 'or',
+        limit: 10,
+        templates: {
+          header: 'Brands',
+        },
+      })
+    )
+  );
+
+  storiesOf('SearchBox').add(
+    'default',
+    wrapWithUnmount(container =>
+      instantsearch.widgets.searchBox({
+        container,
+        placeholder: 'Search for products',
+        poweredBy: true,
+      })
+    )
+  );
+
+  storiesOf('SortBySelector').add(
+    'default',
+    wrapWithUnmount(container =>
+      instantsearch.widgets.sortBySelector({
+        container,
+        indices: [
+          { name: 'instant_search', label: 'Most relevant' },
+          { name: 'instant_search_price_asc', label: 'Lowest price' },
+          { name: 'instant_search_price_desc', label: 'Highest price' },
+        ],
+      })
+    )
+  );
+
+  storiesOf('StarRating').add(
+    'default',
+    wrapWithUnmount(container =>
+      instantsearch.widgets.starRating({
+        container,
+        attributeName: 'rating',
+        max: 5,
+        labels: {
+          andUp: '& Up',
+        },
+        templates: {
+          header: 'Rating',
+        },
+      })
+    )
+  );
+
+  storiesOf('Stats').add(
+    'default',
+    wrapWithUnmount(container => instantsearch.widgets.stats({ container }))
+  );
+
+  storiesOf('Toggle').add(
+    'default',
+    wrapWithUnmount(container =>
+      instantsearch.widgets.toggle({
+        container,
+        attributeName: 'free_shipping',
+        label: 'Free Shipping (toggle single value)',
+        templates: {
+          header: 'Shipping',
+        },
+      })
+    )
+  );
+
+  storiesOf('rangeSlider').add(
+    'default',
+    wrapWithUnmount(container =>
+      instantsearch.widgets.rangeSlider({
+        container,
+        attributeName: 'price',
+        templates: {
+          header: 'Price',
+        },
+        max: 500,
+        step: 10,
+        tooltips: {
+          format(rawValue) {
+            return `$${Math.round(rawValue).toLocaleString()}`;
+          },
+        },
+      })
+    )
+  );
+};
diff --git a/docgen/src/guides/custom-widget.md b/docgen/src/guides/custom-widget.md
index 4a7209aa4a..ddd0f4c7f9 100644
--- a/docgen/src/guides/custom-widget.md
+++ b/docgen/src/guides/custom-widget.md
@@ -32,14 +32,15 @@ There's a simple example of a custom widget at the end of this guide.
 
 ## The widget lifecycle and API
 
-InstantSearch.js defines the widget lifecycle of the widgets in 3 steps:
+InstantSearch.js defines the widget lifecycle of the widgets in 4 steps:
 
  - the configuration step, during which the initial search configuration is computed
  - the init step, which happens before the first search
  - the render step, which happens after each result from Algolia
+ - the dispose step, which happens when you remove the widget or dispose the InstantSearch instance
 
 Thoses steps translate directly into the widget API. Widgets are defined as plain
-JS objects with 3 methods:
+JS objects with 4 methods:
 
  - `getConfiguration` (optional), returns the necessary subpart of the configuration, specific
     to this widget
@@ -47,6 +48,8 @@ JS objects with 3 methods:
     Called before the first search.
  - `render`, optional, used to update the widget with the new information from the results.
     Called after each time results come back from Algolia
+ - `dispose` optional, used to remove the specific configuration which was specified in the `getConfiguration` method.
+    Called when removing the widget or when InstantSearch disposes itself.
 
 If we translate this to code, this looks like:
 
@@ -69,6 +72,13 @@ search.addWidget({
     //   - helper: to modify the search state and propagate the user interaction
     //   - state: the state at this point
     //   - createURL: if the url sync is active, will make it possible to create new URLs
+  },
+  dispose: function(disposeOptions) {
+    // disposeOptions contains one key:
+    //   - state: the state at this point to
+    //
+    // The dispose method should return the next state of the search,
+    // if it has been modified.
   }
 });
 ```
@@ -80,8 +90,8 @@ A widget is valid as long as it implements at least `render` or `init`.
 The previous custom widget API boilerplate is the reading part of the widgets. To be able to transform
 user interaction into search parameters we need to be able to modify the state.
 
-The whole search state is held by an instance of the 
-[JS Helper](https://community.algolia.com/algoliasearch-helper-js/) in InstantSearch.js. 
+The whole search state is held by an instance of the
+[JS Helper](https://community.algolia.com/algoliasearch-helper-js/) in InstantSearch.js.
 This instance of the helper is accessible at the `init` and `render` phases.
 
 The helper is used to change the parameters of the search. It provides methods
diff --git a/src/connectors/clear-all/connectClearAll.js b/src/connectors/clear-all/connectClearAll.js
index bdd74be8ea..08539482c3 100644
--- a/src/connectors/clear-all/connectClearAll.js
+++ b/src/connectors/clear-all/connectClearAll.js
@@ -61,6 +61,7 @@ const refine = ({
  *
  * @type {Connector}
  * @param {function(ClearAllRenderingOptions, boolean)} renderFn Rendering function for the custom **ClearAll** widget.
+ * @param {function} unmountFn Unmount function called when the widget is disposed.
  * @return {function(CustomClearAllWidgetOptions)} Re-usable widget factory for a custom **ClearAll** widget.
  * @example
  * // custom `renderFn` to render the custom ClearAll widget
@@ -90,7 +91,7 @@ const refine = ({
  *   })
  * );
  */
-export default function connectClearAll(renderFn) {
+export default function connectClearAll(renderFn, unmountFn) {
   checkRendering(renderFn, usage);
 
   return (widgetParams = {}) => {
@@ -165,6 +166,10 @@ export default function connectClearAll(renderFn) {
           false
         );
       },
+
+      dispose() {
+        unmountFn();
+      },
     };
   };
 }
diff --git a/src/connectors/current-refined-values/connectCurrentRefinedValues.js b/src/connectors/current-refined-values/connectCurrentRefinedValues.js
index fbda22edde..0125e88f0b 100644
--- a/src/connectors/current-refined-values/connectCurrentRefinedValues.js
+++ b/src/connectors/current-refined-values/connectCurrentRefinedValues.js
@@ -88,6 +88,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  * the widget options used.
  * @type {Connector}
  * @param {function(CurrentRefinedValuesRenderingOptions)} renderFn Rendering function for the custom **CurrentRefinedValues** widget.
+ * @param {function} unmountFn Unmount function called when the widget is disposed.
  * @return {function(CustomCurrentRefinedValuesWidgetOptions)} Re-usable widget factory for a custom **CurrentRefinedValues** widget.
  * @example
  * // custom `renderFn` to render the custom ClearAll widget
@@ -149,7 +150,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  *   })
  * );
  */
-export default function connectCurrentRefinedValues(renderFn) {
+export default function connectCurrentRefinedValues(renderFn, unmountFn) {
   checkRendering(renderFn, usage);
 
   return (widgetParams = {}) => {
@@ -270,6 +271,10 @@ export default function connectCurrentRefinedValues(renderFn) {
           false
         );
       },
+
+      dispose() {
+        unmountFn();
+      },
     };
   };
 }
diff --git a/src/connectors/hierarchical-menu/connectHierarchicalMenu.js b/src/connectors/hierarchical-menu/connectHierarchicalMenu.js
index 5ebdecd31d..1405e4dd74 100644
--- a/src/connectors/hierarchical-menu/connectHierarchicalMenu.js
+++ b/src/connectors/hierarchical-menu/connectHierarchicalMenu.js
@@ -68,9 +68,10 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
   *  [hierarchicalMenu.js](https://github.com/algolia/instantsearch.js/blob/develop/dev/app/custom-widgets/jquery/hierarchicalMenu.js)
   * @type {Connector}
   * @param {function(HierarchicalMenuRenderingOptions)} renderFn Rendering function for the custom **HierarchicalMenu** widget.
+  * @param {function} unmountFn Unmount function called when the widget is disposed.
   * @return {function(CustomHierarchicalMenuWidgetOptions)} Re-usable widget factory for a custom **HierarchicalMenu** widget.
   */
-export default function connectHierarchicalMenu(renderFn) {
+export default function connectHierarchicalMenu(renderFn, unmountFn) {
   checkRendering(renderFn, usage);
 
   return (widgetParams = {}) => {
@@ -190,6 +191,22 @@ export default function connectHierarchicalMenu(renderFn) {
           false
         );
       },
+
+      dispose({ state }) {
+        // unmount widget from DOM
+        unmountFn();
+
+        // compute nextState for the search
+        const nextState = state
+          .removeHierarchicalFacetRefinement(hierarchicalFacetName)
+          .removeHierarchicalFacet(hierarchicalFacetName);
+
+        if (nextState.maxValuesPerFacet === limit) {
+          nextState.setQueryParameters('maxValuesPerFacet', undefined);
+        }
+
+        return nextState;
+      },
     };
   };
 }
diff --git a/src/connectors/hits-per-page/connectHitsPerPage.js b/src/connectors/hits-per-page/connectHitsPerPage.js
index 0f799c7a79..b3c5c36020 100644
--- a/src/connectors/hits-per-page/connectHitsPerPage.js
+++ b/src/connectors/hits-per-page/connectHitsPerPage.js
@@ -58,6 +58,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  * This connector provides a `refine()` function to change the hits per page configuration and trigger a new search.
  * @type {Connector}
  * @param {function(HitsPerPageRenderingOptions, boolean)} renderFn Rendering function for the custom **HitsPerPage** widget.
+ * @param {function} unmountFn Unmount function called when the widget is disposed.
  * @return {function(HitsPerPageWidgetOptions)} Re-usable widget factory for a custom **HitsPerPage** widget.
  * @example
  * // custom `renderFn` to render the custom HitsPerPage widget
@@ -105,7 +106,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  *   })
  * );
  */
-export default function connectHitsPerPage(renderFn) {
+export default function connectHitsPerPage(renderFn, unmountFn) {
   checkRendering(renderFn, usage);
 
   return (widgetParams = {}) => {
@@ -192,6 +193,10 @@ The first one will be picked, you should probably set only one default value`
           isRefined: Number(item.value) === Number(hitsPerPage),
         }));
       },
+
+      dispose() {
+        unmountFn();
+      },
     };
   };
 }
diff --git a/src/connectors/hits/connectHits.js b/src/connectors/hits/connectHits.js
index b1b54a5bcd..b67ce1f65f 100644
--- a/src/connectors/hits/connectHits.js
+++ b/src/connectors/hits/connectHits.js
@@ -34,6 +34,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  * **Hits** connector provides the logic to create custom widgets that will render the results retrieved from Algolia.
  * @type {Connector}
  * @param {function(HitsRenderingOptions, boolean)} renderFn Rendering function for the custom **Hits** widget.
+ * @param {function} unmountFn Unmount function called when the widget is disposed.
  * @return {function(CustomHitsWidgetOptions)} Re-usable widget factory for a custom **Hits** widget.
  * @example
  * // custom `renderFn` to render the custom Hits widget
@@ -55,7 +56,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  *   })
  * );
  */
-export default function connectHits(renderFn) {
+export default function connectHits(renderFn, unmountFn) {
   checkRendering(renderFn, usage);
 
   return (widgetParams = {}) => ({
@@ -90,5 +91,9 @@ export default function connectHits(renderFn) {
         false
       );
     },
+
+    dispose() {
+      unmountFn();
+    },
   });
 }
diff --git a/src/connectors/infinite-hits/connectInfiniteHits.js b/src/connectors/infinite-hits/connectInfiniteHits.js
index 7d3c59b45d..6b73ebcd1a 100644
--- a/src/connectors/infinite-hits/connectInfiniteHits.js
+++ b/src/connectors/infinite-hits/connectInfiniteHits.js
@@ -40,6 +40,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  * This connector provides a `InfiniteHitsRenderingOptions.showMore()` function to load next page of matched results.
  * @type {Connector}
  * @param {function(InfiniteHitsRenderingOptions, boolean)} renderFn Rendering function for the custom **InfiniteHits** widget.
+ * @param {function} unmountFn Unmount function called when the widget is disposed.
  * @return {function(CustomInfiniteHitsWidgetOptions)} Re-usable widget factory for a custom **InfiniteHits** widget.
  * @example
  * // custom `renderFn` to render the custom InfiniteHits widget
@@ -73,7 +74,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  *   })
  * );
  */
-export default function connectInfiniteHits(renderFn) {
+export default function connectInfiniteHits(renderFn, unmountFn) {
   checkRendering(renderFn, usage);
 
   return (widgetParams = {}) => {
@@ -130,6 +131,10 @@ export default function connectInfiniteHits(renderFn) {
           false
         );
       },
+
+      dispose() {
+        unmountFn();
+      },
     };
   };
 }
diff --git a/src/connectors/menu/connectMenu.js b/src/connectors/menu/connectMenu.js
index eb2a9ea208..24133c8adc 100644
--- a/src/connectors/menu/connectMenu.js
+++ b/src/connectors/menu/connectMenu.js
@@ -65,6 +65,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  * **Requirement:** the attribute passed as `attributeName` must be present in "attributes for faceting" on the Algolia dashboard or configured as attributesForFaceting via a set settings call to the Algolia API.
   * @type {Connector}
   * @param {function(MenuRenderingOptions, boolean)} renderFn Rendering function for the custom **Menu** widget. widget.
+  * @param {function} unmountFn Unmount function called when the widget is disposed.
   * @return {function(CustomMenuWidgetOptions)} Re-usable widget factory for a custom **Menu** widget.
   * @example
   * // custom `renderFn` to render the custom Menu widget
@@ -103,7 +104,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
   *   })
   * );
   */
-export default function connectMenu(renderFn) {
+export default function connectMenu(renderFn, unmountFn) {
   checkRendering(renderFn, usage);
 
   return (widgetParams = {}) => {
@@ -228,6 +229,16 @@ export default function connectMenu(renderFn) {
           false
         );
       },
+
+      dispose({ state }) {
+        unmountFn();
+
+        const nextState = state
+          .removeHierarchicalFacetRefinement(attributeName)
+          .removeHierarchicalFacet(attributeName);
+
+        return nextState;
+      },
     };
   };
 }
diff --git a/src/connectors/numeric-refinement-list/connectNumericRefinementList.js b/src/connectors/numeric-refinement-list/connectNumericRefinementList.js
index 41e7a892ae..c8f7306263 100644
--- a/src/connectors/numeric-refinement-list/connectNumericRefinementList.js
+++ b/src/connectors/numeric-refinement-list/connectNumericRefinementList.js
@@ -62,6 +62,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  * @function connectNumericRefinementList
  * @type {Connector}
  * @param {function(NumericRefinementListRenderingOptions, boolean)} renderFn Rendering function for the custom **NumericRefinementList** widget.
+ * @param {function} unmountFn Unmount function called when the widget is disposed.
  * @return {function(CustomNumericRefinementListWidgetOptions)} Re-usable widget factory for a custom **NumericRefinementList** widget.
  * @example
  * // custom `renderFn` to render the custom NumericRefinementList widget
@@ -110,7 +111,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  *   })
  * );
  */
-export default function connectNumericRefinementList(renderFn) {
+export default function connectNumericRefinementList(renderFn, unmountFn) {
   checkRendering(renderFn, usage);
 
   return (widgetParams = {}) => {
@@ -167,6 +168,11 @@ export default function connectNumericRefinementList(renderFn) {
           false
         );
       },
+
+      dispose({ state }) {
+        unmountFn();
+        return state.clearRefinements(attributeName);
+      },
     };
   };
 }
diff --git a/src/connectors/numeric-selector/connectNumericSelector.js b/src/connectors/numeric-selector/connectNumericSelector.js
index de1d27b397..a79b9cc38c 100644
--- a/src/connectors/numeric-selector/connectNumericSelector.js
+++ b/src/connectors/numeric-selector/connectNumericSelector.js
@@ -50,6 +50,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  * It provides a `refine(value)` function to trigger a new search with selected option.
  * @type {Connector}
  * @param {function(NumericSelectorRenderingOptions, boolean)} renderFn Rendering function for the custom **NumericSelector** widget.
+ * @param {function} unmountFn Unmount function called when the widget is disposed.
  * @return {function(CustomNumericSelectorWidgetOptions)} Re-usable widget factory for a custom **NumericSelector** widget.
  * @example
  * // custom `renderFn` to render the custom NumericSelector widget
@@ -92,7 +93,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  *   })
  * );
  */
-export default function connectNumericSelector(renderFn) {
+export default function connectNumericSelector(renderFn, unmountFn) {
   checkRendering(renderFn, usage);
 
   return (widgetParams = {}) => {
@@ -149,6 +150,11 @@ export default function connectNumericSelector(renderFn) {
         );
       },
 
+      dispose({ state }) {
+        unmountFn();
+        return state.removeNumericRefinement(attributeName);
+      },
+
       _getRefinedValue(state) {
         // This is reimplementing state.getNumericRefinement
         // But searchParametersFromUrl is not an actual SearchParameters object
diff --git a/src/connectors/pagination/connectPagination.js b/src/connectors/pagination/connectPagination.js
index e2b6c7cf31..39ee315657 100644
--- a/src/connectors/pagination/connectPagination.js
+++ b/src/connectors/pagination/connectPagination.js
@@ -43,6 +43,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  *
  * @type {Connector}
  * @param {function(PaginationRenderingOptions, boolean)} renderFn Rendering function for the custom **Pagination** widget.
+ * @param {function} unmountFn Unmount function called when the widget is disposed.
  * @return {function(CustomPaginationWidgetOptions)} Re-usable widget factory for a custom **Pagination** widget.
  * @example
  * // custom `renderFn` to render the custom Pagination widget
@@ -89,7 +90,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  *   })
  * );
  */
-export default function connectPagination(renderFn) {
+export default function connectPagination(renderFn, unmountFn) {
   checkRendering(renderFn, usage);
 
   return (widgetParams = {}) => {
@@ -136,6 +137,10 @@ export default function connectPagination(renderFn) {
           false
         );
       },
+
+      dispose() {
+        unmountFn();
+      },
     };
   };
 }
diff --git a/src/connectors/price-ranges/connectPriceRanges.js b/src/connectors/price-ranges/connectPriceRanges.js
index 0c43172910..389cd20c32 100644
--- a/src/connectors/price-ranges/connectPriceRanges.js
+++ b/src/connectors/price-ranges/connectPriceRanges.js
@@ -43,6 +43,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  *
  * @type {Connector}
  * @param {function(PriceRangesRenderingOptions, boolean)} renderFn Rendering function for the custom **PriceRanges** widget.
+ * @param {function} unmountFn Unmount function called when the widget is disposed.
  * @return {function(CustomPriceRangesWidgetOptions)} Re-usable widget factory for a custom **PriceRanges** widget.
  * @example
  * function getLabel(item) {
@@ -97,7 +98,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  *   })
  * );
  */
-export default function connectPriceRanges(renderFn) {
+export default function connectPriceRanges(renderFn, unmountFn) {
   checkRendering(renderFn, usage);
 
   return (widgetParams = {}) => {
@@ -215,6 +216,16 @@ export default function connectPriceRanges(renderFn) {
           false
         );
       },
+
+      dispose({ state }) {
+        unmountFn();
+
+        const nextState = state
+          .removeFacetRefinement(attributeName)
+          .removeFacet(attributeName);
+
+        return nextState;
+      },
     };
   };
 }
diff --git a/src/connectors/range/connectRange.js b/src/connectors/range/connectRange.js
index 1e95e4ac0f..18bb16c76c 100644
--- a/src/connectors/range/connectRange.js
+++ b/src/connectors/range/connectRange.js
@@ -52,9 +52,10 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  * information about the min and max bounds for the current result set.
  * @type {Connector}
  * @param {function(RangeRenderingOptions, boolean)} renderFn Rendering function for the custom **Range** widget.
+ * @param {function} unmountFn Unmount function called when the widget is disposed.
  * @return {function(CustomRangeWidgetOptions)} Re-usable widget factory for a custom **Range** widget.
  */
-export default function connectRange(renderFn) {
+export default function connectRange(renderFn, unmountFn) {
   checkRendering(renderFn, usage);
 
   return (widgetParams = {}) => {
@@ -279,6 +280,16 @@ export default function connectRange(renderFn) {
           false
         );
       },
+
+      dispose({ state }) {
+        unmountFn();
+
+        const nextState = state
+          .removeNumericRefinement(attributeName)
+          .removeDisjunctiveFacet(attributeName);
+
+        return nextState;
+      },
     };
   };
 }
diff --git a/src/connectors/refinement-list/connectRefinementList.js b/src/connectors/refinement-list/connectRefinementList.js
index 9e95c2dfcf..771ce8d20c 100644
--- a/src/connectors/refinement-list/connectRefinementList.js
+++ b/src/connectors/refinement-list/connectRefinementList.js
@@ -91,6 +91,7 @@ export const checkUsage = ({
   * function to select an item.
  * @type {Connector}
  * @param {function(RefinementListRenderingOptions, boolean)} renderFn Rendering function for the custom **RefinementList** widget.
+ * @param {function} unmountFn Unmount function called when the widget is disposed.
  * @return {function(CustomRefinementListWidgetOptions)} Re-usable widget factory for a custom **RefinementList** widget.
  * @example
  * // custom `renderFn` to render the custom RefinementList widget
@@ -144,7 +145,7 @@ export const checkUsage = ({
  *   })
  * );
  */
-export default function connectRefinementList(renderFn) {
+export default function connectRefinementList(renderFn, unmountFn) {
   checkRendering(renderFn, usage);
 
   return (widgetParams = {}) => {
@@ -317,6 +318,7 @@ export default function connectRefinementList(renderFn) {
 
         return widgetConfiguration;
       },
+
       init({ helper, createURL, instantSearchInstance }) {
         this.cachedToggleShowMore = this.cachedToggleShowMore.bind(this);
 
@@ -339,6 +341,7 @@ export default function connectRefinementList(renderFn) {
           hasExhaustiveItems: true,
         });
       },
+
       render(renderOptions) {
         const {
           results,
@@ -370,6 +373,20 @@ export default function connectRefinementList(renderFn) {
           hasExhaustiveItems,
         });
       },
+
+      dispose({ state }) {
+        unmountFn();
+
+        if (operator === 'and') {
+          return state
+            .removeFacetRefinement(attributeName)
+            .removeFacet(attributeName);
+        } else {
+          return state
+            .removeDisjunctiveFacetRefinement(attributeName)
+            .removeDisjunctiveFacet(attributeName);
+        }
+      },
     };
   };
 }
diff --git a/src/connectors/search-box/connectSearchBox.js b/src/connectors/search-box/connectSearchBox.js
index 7a7668ce4e..0e47fbe4ad 100644
--- a/src/connectors/search-box/connectSearchBox.js
+++ b/src/connectors/search-box/connectSearchBox.js
@@ -44,6 +44,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  * may be impacted by the `queryHook` widget parameter.
  * @type {Connector}
  * @param {function(SearchBoxRenderingOptions, boolean)} renderFn Rendering function for the custom **SearchBox** widget.
+ * @param {function} unmountFn Unmount function called when the widget is disposed.
  * @return {function(CustomSearchBoxWidgetOptions)} Re-usable widget factory for a custom **SearchBox** widget.
  * @example
  * // custom `renderFn` to render the custom SearchBox widget
@@ -71,7 +72,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  *   })
  * );
  */
-export default function connectSearchBox(renderFn) {
+export default function connectSearchBox(renderFn, unmountFn) {
   checkRendering(renderFn, usage);
 
   return (widgetParams = {}) => {
@@ -141,6 +142,11 @@ export default function connectSearchBox(renderFn) {
           false
         );
       },
+
+      dispose({ state }) {
+        unmountFn();
+        return state.setQuery('');
+      },
     };
   };
 }
diff --git a/src/connectors/sort-by-selector/connectSortBySelector.js b/src/connectors/sort-by-selector/connectSortBySelector.js
index c22991035f..53b9088c15 100644
--- a/src/connectors/sort-by-selector/connectSortBySelector.js
+++ b/src/connectors/sort-by-selector/connectSortBySelector.js
@@ -49,6 +49,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  * with `options.value`.
  * @type {Connector}
  * @param {function(SortBySelectorRenderingOptions, boolean)} renderFn Rendering function for the custom **SortBySelector** widget.
+ * @param {function} unmountFn Unmount function called when the widget is disposed.
  * @return {function(CustomSortBySelectorWidgetOptions)} Re-usable widget factory for a custom **SortBySelector** widget.
  * @example
  * // custom `renderFn` to render the custom SortBySelector widget
@@ -93,7 +94,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  *   })
  * );
  */
-export default function connectSortBySelector(renderFn) {
+export default function connectSortBySelector(renderFn, unmountFn) {
   checkRendering(renderFn, usage);
 
   return (widgetParams = {}) => {
@@ -122,6 +123,7 @@ export default function connectSortBySelector(renderFn) {
           );
         }
 
+        this.initialIndex = currentIndex;
         this.setIndex = indexName => helper.setIndex(indexName).search();
 
         renderFn(
@@ -150,6 +152,11 @@ export default function connectSortBySelector(renderFn) {
           false
         );
       },
+
+      dispose({ state }) {
+        unmountFn();
+        return state.setIndex(this.initialIndex);
+      },
     };
   };
 }
diff --git a/src/connectors/star-rating/connectStarRating.js b/src/connectors/star-rating/connectStarRating.js
index 95b9c8b2e8..6b86a2be98 100644
--- a/src/connectors/star-rating/connectStarRating.js
+++ b/src/connectors/star-rating/connectStarRating.js
@@ -55,6 +55,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  * with `items.value`.
  * @type {Connector}
  * @param {function(StarRatingRenderingOptions, boolean)} renderFn Rendering function for the custom **StarRating** widget.
+ * @param {function} unmountFn Unmount function called when the widget is disposed.
  * @return {function(CustomStarRatingWidgetOptions)} Re-usable widget factory for a custom **StarRating** widget.
  * @example
  * // custom `renderFn` to render the custom StarRating widget
@@ -103,7 +104,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  *   })
  * );
  */
-export default function connectStarRating(renderFn) {
+export default function connectStarRating(renderFn, unmountFn) {
   checkRendering(renderFn, usage);
 
   return (widgetParams = {}) => {
@@ -185,6 +186,16 @@ export default function connectStarRating(renderFn) {
         );
       },
 
+      dispose({ state }) {
+        unmountFn();
+
+        const nextState = state
+          .removeDisjunctiveFacetRefinement(attributeName)
+          .removeDisjunctiveFacet(attributeName);
+
+        return nextState;
+      },
+
       _toggleRefinement(helper, facetValue) {
         const isRefined = this._getRefinedStar(helper) === Number(facetValue);
         helper.clearRefinements(attributeName);
diff --git a/src/connectors/stats/connectStats.js b/src/connectors/stats/connectStats.js
index 88fad87626..6561d1cb5a 100644
--- a/src/connectors/stats/connectStats.js
+++ b/src/connectors/stats/connectStats.js
@@ -33,6 +33,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  *
  * @type {Connector}
  * @param {function(StatsRenderingOptions, boolean)} renderFn Rendering function for the custom **Stats** widget.
+ * @param {function} unmountFn Unmount function called when the widget is disposed.
  * @return {function} Re-usable widget factory for a custom **Stats** widget.
  * @example
  * // custom `renderFn` to render the custom Stats widget
@@ -53,7 +54,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  *   })
  * );
  */
-export default function connectStats(renderFn) {
+export default function connectStats(renderFn, unmountFn) {
   checkRendering(renderFn, usage);
 
   return (widgetParams = {}) => ({
@@ -88,5 +89,9 @@ export default function connectStats(renderFn) {
         false
       );
     },
+
+    dispose() {
+      unmountFn();
+    },
   });
 }
diff --git a/src/connectors/toggle/connectToggle.js b/src/connectors/toggle/connectToggle.js
index 4f25199a82..2feac35620 100644
--- a/src/connectors/toggle/connectToggle.js
+++ b/src/connectors/toggle/connectToggle.js
@@ -60,6 +60,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  *
  * @type {Connector}
  * @param {function(ToggleRenderingOptions, boolean)} renderFn Rendering function for the custom **Toggle** widget.
+ * @param {function} unmountFn Unmount function called when the widget is disposed.
  * @return {function(CustomToggleWidgetOptions)} Re-usable widget factory for a custom **Toggle** widget.
  * @example
  * // custom `renderFn` to render the custom ClearAll widget
@@ -102,7 +103,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  *   })
  * );
  */
-export default function connectToggle(renderFn) {
+export default function connectToggle(renderFn, unmountFn) {
   checkRendering(renderFn, usage);
 
   return (widgetParams = {}) => {
@@ -262,6 +263,16 @@ export default function connectToggle(renderFn) {
           false
         );
       },
+
+      dispose({ state }) {
+        unmountFn();
+
+        const nextState = state
+          .removeDisjunctiveFacetRefinement(attributeName)
+          .removeDisjunctiveFacet(attributeName);
+
+        return nextState;
+      },
     };
   };
 }
diff --git a/src/lib/InstantSearch.js b/src/lib/InstantSearch.js
index 2c2e65ce08..a24411aac0 100644
--- a/src/lib/InstantSearch.js
+++ b/src/lib/InstantSearch.js
@@ -82,12 +82,108 @@ Usage: instantsearch({
    * @return {undefined} This method does not return anything
    */
   addWidget(widget) {
-    // Add the widget to the list of widget
-    if (widget.render === undefined && widget.init === undefined) {
-      throw new Error('Widget definition missing render or init method');
+    this.addWidgets([widget]);
+  }
+
+  /**
+   * Add multiple widgets
+   * @param  {Widget[]} widgets The array of widgets to add to InstantSearch.
+   * @return {undefined} This method does not return anything
+   */
+  addWidgets(widgets) {
+    if (!Array.isArray(widgets)) {
+      throw new Error(
+        'You need to provide an array of widgets or call `addWidget()`'
+      );
+    }
+
+    widgets.forEach(widget => {
+      // Add the widget to the list of widget
+      if (widget.render === undefined && widget.init === undefined) {
+        throw new Error('Widget definition missing render or init method');
+      }
+
+      this.widgets.push(widget);
+    });
+
+    // Init the widget directly if instantsearch has been already started
+    if (this.started) {
+      this.searchParameters = this.widgets.reduce(enhanceConfiguration({}), {
+        ...this.helper.state,
+      });
+
+      this.helper.setState(this.searchParameters);
+
+      widgets.forEach(widget => {
+        if (widget.init) {
+          widget.init({
+            state: this.helper.state,
+            helper: this.helper,
+            templatesConfig: this.templatesConfig,
+            createURL: this._createAbsoluteURL,
+            onHistoryChange: this._onHistoryChange,
+            instantSearchInstance: this,
+          });
+        }
+      });
+
+      this.helper.search();
     }
+  }
 
-    this.widgets.push(widget);
+  /**
+   * Remove a widget
+   * @param  {Widget} widget The widget instance to remove from InstantSearch. This widget must implement a `dipose()` method in order to be gracefully removed.
+   * @return {undefined} This method does not return anything
+   */
+  removeWidget(widget) {
+    this.removeWidgets([widget]);
+  }
+
+  /**
+   * Remove multiple widgets
+   * @param  {Widget[]} widgets Array of widgets instances to remove from InstantSearch.
+   * @return {undefined} This method does not return anything
+   */
+  removeWidgets(widgets) {
+    if (!Array.isArray(widgets)) {
+      throw new Error(
+        'You need to provide an array of widgets or call `removeWidget()`'
+      );
+    }
+
+    widgets.forEach(widget => {
+      if (
+        !this.widgets.includes(widget) ||
+        typeof widget.dispose !== 'function'
+      ) {
+        throw new Error(
+          'The widget you tried to remove does not implement the dispose method, therefore it is not possible to remove this widget'
+        );
+      }
+
+      this.widgets = this.widgets.filter(w => w !== widget);
+
+      const nextState = widget.dispose({
+        helper: this.helper,
+        state: this.helper.getState(),
+      });
+
+      // re-compute remaining widgets to the state
+      // in a case two widgets were using the same configuration but we removed one
+      if (nextState) {
+        this.searchParameters = this.widgets.reduce(enhanceConfiguration({}), {
+          ...nextState,
+        });
+
+        this.helper.setState(this.searchParameters);
+      }
+    });
+
+    // no need to retrigger a search if we don't have any widgets left
+    if (this.widgets.length > 0) {
+      this.helper.search();
+    }
   }
 
   /**
@@ -101,6 +197,8 @@ Usage: instantsearch({
     if (!this.widgets)
       throw new Error('No widgets were added to instantsearch.js');
 
+    if (this.started) throw new Error('start() has been already called once');
+
     let searchParametersFromUrl;
 
     if (this.urlSync) {
@@ -151,6 +249,22 @@ Usage: instantsearch({
     this._init(helper.state, this.helper);
     this.helper.on('result', this._render.bind(this, this.helper));
     this.helper.search();
+
+    // track we started the search if we add more widgets,
+    // to init them directly after add
+    this.started = true;
+  }
+
+  /**
+   * Remove all widgets without triggering a search afterwards.
+   * @return {undefined} This method does not return anything
+   */
+  dispose() {
+    this.removeWidgets(
+      this.widgets
+        .slice()
+        .sort(widget => (widget.constructor.name === 'URLSync' ? -1 : 1))
+    );
   }
 
   createURL(params) {
diff --git a/src/lib/__tests__/InstantSearch-test.js b/src/lib/__tests__/InstantSearch-test.js
index 062cf8db09..fc27f3cb92 100644
--- a/src/lib/__tests__/InstantSearch-test.js
+++ b/src/lib/__tests__/InstantSearch-test.js
@@ -1,4 +1,5 @@
 import range from 'lodash/range';
+import times from 'lodash/times';
 import sinon from 'sinon';
 
 import algoliaSearchHelper from 'algoliasearch-helper';
@@ -361,4 +362,260 @@ describe('InstantSearch lifecycle', () => {
       expect(onRender.callCount).toEqual(1);
     });
   });
+
+  describe('When removing a widget', () => {
+    function registerWidget(
+      widgetGetConfiguration = {
+        facets: ['categories'],
+        maxValuesPerFacet: 10,
+      },
+      dispose = sinon.spy()
+    ) {
+      const widget = {
+        getConfiguration: sinon.stub().returns(widgetGetConfiguration),
+        init: sinon.spy(),
+        render: sinon.spy(),
+        dispose,
+      };
+
+      search.addWidget(widget);
+
+      return widget;
+    }
+
+    beforeEach(() => {
+      search = new InstantSearch({
+        appId,
+        apiKey,
+        indexName,
+      });
+    });
+
+    it('should unmount a widget without configuration', () => {
+      const widget1 = registerWidget({});
+      const widget2 = registerWidget({});
+
+      expect(search.widgets.length).toBe(2);
+
+      search.start();
+      search.removeWidget(widget1);
+      search.removeWidget(widget2);
+
+      expect(search.widgets.length).toBe(0);
+    });
+
+    it('should unmount a widget with facets configuration', () => {
+      const widget1 = registerWidget({ facets: ['price'] }, ({ state }) =>
+        state.removeFacet('price')
+      );
+      search.start();
+
+      expect(search.widgets.length).toBe(1);
+      expect(search.searchParameters.facets).toEqual(['price']);
+
+      search.removeWidget(widget1);
+
+      expect(search.widgets.length).toBe(0);
+      expect(search.searchParameters.facets).toEqual([]);
+    });
+
+    it('should unmount a widget with hierarchicalFacets configuration', () => {
+      const widget1 = registerWidget(
+        {
+          hierarchicalFacets: [
+            {
+              name: 'price',
+              attributes: ['foo'],
+              separator: ' > ',
+              rootPath: 'lvl1',
+              showParentLevel: true,
+            },
+          ],
+        },
+        ({ state }) => state.removeHierarchicalFacet('price')
+      );
+      search.start();
+
+      expect(search.widgets.length).toBe(1);
+      expect(search.searchParameters.hierarchicalFacets).toEqual([
+        {
+          name: 'price',
+          attributes: ['foo'],
+          separator: ' > ',
+          rootPath: 'lvl1',
+          showParentLevel: true,
+        },
+      ]);
+
+      search.removeWidget(widget1);
+
+      expect(search.widgets.length).toBe(0);
+      expect(search.searchParameters.hierarchicalFacets).toEqual([]);
+    });
+
+    it('should unmount a widget with disjunctiveFacets configuration', () => {
+      const widget1 = registerWidget(
+        { disjunctiveFacets: ['price'] },
+        ({ state }) => state.removeDisjunctiveFacet('price')
+      );
+      search.start();
+
+      expect(search.widgets.length).toBe(1);
+      expect(search.searchParameters.disjunctiveFacets).toEqual(['price']);
+
+      search.removeWidget(widget1);
+
+      expect(search.widgets.length).toBe(0);
+      expect(search.searchParameters.disjunctiveFacets).toEqual([]);
+    });
+
+    it('should unmount a widget with numericRefinements configuration', () => {
+      const widget1 = registerWidget(
+        { numericRefinements: { price: {} } },
+        ({ state }) => state.removeNumericRefinement('price')
+      );
+      search.start();
+
+      expect(search.widgets.length).toBe(1);
+      expect(search.searchParameters.numericRefinements).toEqual({ price: {} });
+
+      search.removeWidget(widget1);
+
+      expect(search.widgets.length).toBe(0);
+      expect(search.searchParameters.numericRefinements).toEqual({});
+    });
+
+    it('should unmount a widget with maxValuesPerFacet configuration', () => {
+      const widget1 = registerWidget(undefined, ({ state }) =>
+        state
+          .removeFacet('categories')
+          .setQueryParameters('maxValuesPerFacet', undefined)
+      );
+      search.start();
+
+      expect(search.widgets.length).toBe(1);
+      expect(search.searchParameters.facets).toEqual(['categories']);
+      expect(search.searchParameters.maxValuesPerFacet).toEqual(10);
+
+      search.removeWidget(widget1);
+
+      expect(search.widgets.length).toBe(0);
+      expect(search.searchParameters.facets).toEqual([]);
+      expect(search.searchParameters.maxValuesPerFacet).toBe(undefined);
+    });
+
+    it('should unmount multiple widgets at once', () => {
+      const widget1 = registerWidget(
+        { numericRefinements: { price: {} } },
+        ({ state }) => state.removeNumericRefinement('price')
+      );
+      const widget2 = registerWidget(
+        { disjunctiveFacets: ['price'] },
+        ({ state }) => state.removeDisjunctiveFacet('price')
+      );
+
+      search.start();
+
+      expect(search.widgets.length).toBe(2);
+      expect(search.searchParameters.numericRefinements).toEqual({ price: {} });
+      expect(search.searchParameters.disjunctiveFacets).toEqual(['price']);
+
+      search.removeWidgets([widget1, widget2]);
+
+      expect(search.widgets.length).toBe(0);
+      expect(search.searchParameters.numericRefinements).toEqual({});
+      expect(search.searchParameters.disjunctiveFacets).toEqual([]);
+    });
+  });
+
+  describe('When adding widgets after start', () => {
+    function registerWidget(
+      widgetGetConfiguration = {},
+      dispose = sinon.spy()
+    ) {
+      const widget = {
+        getConfiguration: sinon.stub().returns(widgetGetConfiguration),
+        init: sinon.spy(),
+        render: sinon.spy(),
+        dispose,
+      };
+
+      return widget;
+    }
+
+    beforeEach(() => {
+      search = new InstantSearch({
+        appId,
+        apiKey,
+        indexName,
+      });
+    });
+
+    it('should add widgets after start', () => {
+      search.start();
+      expect(helperSearchSpy.callCount).toBe(1);
+
+      expect(search.widgets.length).toBe(0);
+      expect(search.started).toBe(true);
+
+      const widget1 = registerWidget({ facets: ['price'] });
+      search.addWidget(widget1);
+
+      expect(helperSearchSpy.callCount).toBe(2);
+      expect(widget1.init.calledOnce).toBe(true);
+
+      const widget2 = registerWidget({ disjunctiveFacets: ['categories'] });
+      search.addWidget(widget2);
+
+      expect(widget2.init.calledOnce).toBe(true);
+      expect(helperSearchSpy.callCount).toBe(3);
+
+      expect(search.widgets.length).toBe(2);
+      expect(search.searchParameters.facets).toEqual(['price']);
+      expect(search.searchParameters.disjunctiveFacets).toEqual(['categories']);
+    });
+
+    it('should trigger only one search using `addWidgets()`', () => {
+      search.start();
+
+      expect(helperSearchSpy.callCount).toBe(1);
+      expect(search.widgets.length).toBe(0);
+      expect(search.started).toBe(true);
+
+      const widget1 = registerWidget({ facets: ['price'] });
+      const widget2 = registerWidget({ disjunctiveFacets: ['categories'] });
+
+      search.addWidgets([widget1, widget2]);
+
+      expect(helperSearchSpy.callCount).toBe(2);
+      expect(search.searchParameters.facets).toEqual(['price']);
+      expect(search.searchParameters.disjunctiveFacets).toEqual(['categories']);
+    });
+  });
+
+  it('should remove all widgets without triggering a search on dispose', () => {
+    search = new InstantSearch({
+      appId,
+      apiKey,
+      indexName,
+    });
+
+    const widgets = times(5, () => ({
+      getConfiguration: () => ({}),
+      init: jest.fn(),
+      render: jest.fn(),
+      dispose: jest.fn(),
+    }));
+
+    search.addWidgets(widgets);
+    search.start();
+
+    expect(search.widgets.length).toBe(5);
+    expect(helperSearchSpy.callCount).toBe(1);
+
+    search.dispose();
+
+    expect(search.widgets.length).toBe(0);
+    expect(helperSearchSpy.callCount).toBe(1);
+  });
 });
diff --git a/src/lib/url-sync.js b/src/lib/url-sync.js
index 60648024b4..ff1cf91bfd 100644
--- a/src/lib/url-sync.js
+++ b/src/lib/url-sync.js
@@ -31,14 +31,16 @@ const hashUrlUtils = {
   ignoreNextPopState: false,
   character: '#',
   onpopstate(cb) {
-    window.addEventListener('hashchange', hash => {
+    this._onHashChange = hash => {
       if (this.ignoreNextPopState) {
         this.ignoreNextPopState = false;
         return;
       }
 
       cb(hash);
-    });
+    };
+
+    window.addEventListener('hashchange', this._onHashChange);
   },
   pushState(qs) {
     // hash change or location assign does trigger an hashchange event
@@ -54,6 +56,10 @@ const hashUrlUtils = {
   readUrl() {
     return window.location.hash.slice(1);
   },
+  dispose() {
+    window.removeEventListener('hashchange', this._onHashChange);
+    window.location.assign(getFullURL(''));
+  },
 };
 
 /**
@@ -63,7 +69,8 @@ const hashUrlUtils = {
 const modernUrlUtils = {
   character: '?',
   onpopstate(cb) {
-    window.addEventListener('popstate', cb);
+    this._onPopState = (...args) => cb(...args);
+    window.addEventListener('popstate', this._onPopState);
   },
   pushState(qs, { getHistoryState }) {
     window.history.pushState(
@@ -78,6 +85,10 @@ const modernUrlUtils = {
   readUrl() {
     return window.location.search.slice(1);
   },
+  dispose() {
+    window.removeEventListener('popstate', this._onPopState);
+    window.history.pushState(null, null, getFullURL(''));
+  },
 };
 
 // we always push the full url to the url bar. Not a relative one.
@@ -154,6 +165,11 @@ class URLSync {
     }
   }
 
+  dispose({ helper }) {
+    helper.removeListener('change', this.renderURLFromState);
+    this.urlUtils.dispose();
+  }
+
   onPopState(helper, fullState) {
     clearTimeout(this.urlUpdateTimeout);
     // compare with helper.state
diff --git a/src/widgets/clear-all/clear-all.js b/src/widgets/clear-all/clear-all.js
index 9f64de3d42..b915f20029 100644
--- a/src/widgets/clear-all/clear-all.js
+++ b/src/widgets/clear-all/clear-all.js
@@ -1,4 +1,4 @@
-import React, { render } from 'preact-compat';
+import React, { render, unmountComponentAtNode } from 'preact-compat';
 import ClearAllWithHOCs from '../../components/ClearAll/ClearAll.js';
 import cx from 'classnames';
 
@@ -142,7 +142,9 @@ export default function clearAll({
   });
 
   try {
-    const makeWidget = connectClearAll(specializedRenderer);
+    const makeWidget = connectClearAll(specializedRenderer, () =>
+      unmountComponentAtNode(containerNode)
+    );
     return makeWidget({ excludeAttributes, clearsQuery });
   } catch (e) {
     throw new Error(usage);
diff --git a/src/widgets/current-refined-values/current-refined-values.js b/src/widgets/current-refined-values/current-refined-values.js
index 0ff18ed731..28b5f03fe6 100644
--- a/src/widgets/current-refined-values/current-refined-values.js
+++ b/src/widgets/current-refined-values/current-refined-values.js
@@ -1,4 +1,4 @@
-import React, { render } from 'preact-compat';
+import React, { render, unmountComponentAtNode } from 'preact-compat';
 import cx from 'classnames';
 
 import isUndefined from 'lodash/isUndefined';
@@ -269,7 +269,8 @@ export default function currentRefinedValues({
 
   try {
     const makeCurrentRefinedValues = connectCurrentRefinedValues(
-      specializedRenderer
+      specializedRenderer,
+      () => unmountComponentAtNode(containerNode)
     );
     return makeCurrentRefinedValues({
       attributes,
diff --git a/src/widgets/hierarchical-menu/hierarchical-menu.js b/src/widgets/hierarchical-menu/hierarchical-menu.js
index 16da14b5cc..642d003488 100644
--- a/src/widgets/hierarchical-menu/hierarchical-menu.js
+++ b/src/widgets/hierarchical-menu/hierarchical-menu.js
@@ -1,4 +1,4 @@
-import React, { render } from 'preact-compat';
+import React, { render, unmountComponentAtNode } from 'preact-compat';
 import cx from 'classnames';
 
 import connectHierarchicalMenu from '../../connectors/hierarchical-menu/connectHierarchicalMenu';
@@ -232,7 +232,10 @@ export default function hierarchicalMenu(
   });
 
   try {
-    const makeHierarchicalMenu = connectHierarchicalMenu(specializedRenderer);
+    const makeHierarchicalMenu = connectHierarchicalMenu(
+      specializedRenderer,
+      () => unmountComponentAtNode(containerNode)
+    );
     return makeHierarchicalMenu({
       attributes,
       separator,
diff --git a/src/widgets/hits-per-page-selector/hits-per-page-selector.js b/src/widgets/hits-per-page-selector/hits-per-page-selector.js
index 5e6ce76cc1..fba32dbfb1 100644
--- a/src/widgets/hits-per-page-selector/hits-per-page-selector.js
+++ b/src/widgets/hits-per-page-selector/hits-per-page-selector.js
@@ -1,4 +1,4 @@
-import React, { render } from 'preact-compat';
+import React, { render, unmountComponentAtNode } from 'preact-compat';
 import cx from 'classnames';
 
 import find from 'lodash/find';
@@ -111,7 +111,10 @@ export default function hitsPerPageSelector(
   });
 
   try {
-    const makeHitsPerPageSelector = connectHitsPerPage(specializedRenderer);
+    const makeHitsPerPageSelector = connectHitsPerPage(
+      specializedRenderer,
+      () => unmountComponentAtNode(containerNode)
+    );
     return makeHitsPerPageSelector({ items });
   } catch (e) {
     throw new Error(usage);
diff --git a/src/widgets/hits/hits.js b/src/widgets/hits/hits.js
index f61273570a..2f4319e53b 100644
--- a/src/widgets/hits/hits.js
+++ b/src/widgets/hits/hits.js
@@ -1,4 +1,4 @@
-import React, { render } from 'preact-compat';
+import React, { render, unmountComponentAtNode } from 'preact-compat';
 import cx from 'classnames';
 
 import Hits from '../../components/Hits.js';
@@ -135,7 +135,9 @@ export default function hits({
   });
 
   try {
-    const makeHits = connectHits(specializedRenderer);
+    const makeHits = connectHits(specializedRenderer, () =>
+      unmountComponentAtNode(containerNode)
+    );
     return makeHits({ escapeHits });
   } catch (e) {
     throw new Error(usage);
diff --git a/src/widgets/infinite-hits/infinite-hits.js b/src/widgets/infinite-hits/infinite-hits.js
index f33c647280..4e7fcdd9d0 100644
--- a/src/widgets/infinite-hits/infinite-hits.js
+++ b/src/widgets/infinite-hits/infinite-hits.js
@@ -1,4 +1,4 @@
-import React, { render } from 'preact-compat';
+import React, { render, unmountComponentAtNode } from 'preact-compat';
 import cx from 'classnames';
 
 import InfiniteHits from '../../components/InfiniteHits.js';
@@ -143,7 +143,9 @@ export default function infiniteHits(
   });
 
   try {
-    const makeInfiniteHits = connectInfiniteHits(specializedRenderer);
+    const makeInfiniteHits = connectInfiniteHits(specializedRenderer, () =>
+      unmountComponentAtNode(containerNode)
+    );
     return makeInfiniteHits({ escapeHits });
   } catch (e) {
     throw new Error(usage);
diff --git a/src/widgets/menu/menu.js b/src/widgets/menu/menu.js
index 29a011a814..dd6f6d0c1f 100644
--- a/src/widgets/menu/menu.js
+++ b/src/widgets/menu/menu.js
@@ -1,4 +1,4 @@
-import React, { render } from 'preact-compat';
+import React, { render, unmountComponentAtNode } from 'preact-compat';
 import cx from 'classnames';
 
 import defaultTemplates from './defaultTemplates.js';
@@ -217,7 +217,9 @@ export default function menu({
   });
 
   try {
-    const makeWidget = connectMenu(specializedRenderer);
+    const makeWidget = connectMenu(specializedRenderer, () =>
+      unmountComponentAtNode(containerNode)
+    );
     return makeWidget({ attributeName, limit, sortBy, showMoreLimit });
   } catch (e) {
     throw new Error(usage);
diff --git a/src/widgets/numeric-refinement-list/numeric-refinement-list.js b/src/widgets/numeric-refinement-list/numeric-refinement-list.js
index 95a3af9fd3..66874884ff 100644
--- a/src/widgets/numeric-refinement-list/numeric-refinement-list.js
+++ b/src/widgets/numeric-refinement-list/numeric-refinement-list.js
@@ -1,4 +1,4 @@
-import React, { render } from 'preact-compat';
+import React, { render, unmountComponentAtNode } from 'preact-compat';
 import cx from 'classnames';
 
 import RefinementList from '../../components/RefinementList/RefinementList.js';
@@ -177,7 +177,8 @@ export default function numericRefinementList(
   });
   try {
     const makeNumericRefinementList = connectNumericRefinementList(
-      specializedRenderer
+      specializedRenderer,
+      () => unmountComponentAtNode(containerNode)
     );
     return makeNumericRefinementList({ attributeName, options });
   } catch (e) {
diff --git a/src/widgets/numeric-selector/numeric-selector.js b/src/widgets/numeric-selector/numeric-selector.js
index 8043be7440..38d065c1cb 100644
--- a/src/widgets/numeric-selector/numeric-selector.js
+++ b/src/widgets/numeric-selector/numeric-selector.js
@@ -1,4 +1,4 @@
-import React, { render } from 'preact-compat';
+import React, { render, unmountComponentAtNode } from 'preact-compat';
 import cx from 'classnames';
 
 import Selector from '../../components/Selector.js';
@@ -112,7 +112,10 @@ export default function numericSelector({
   });
 
   try {
-    const makeNumericSelector = connectNumericSelector(specializedRenderer);
+    const makeNumericSelector = connectNumericSelector(
+      specializedRenderer,
+      () => unmountComponentAtNode(containerNode)
+    );
     return makeNumericSelector({ operator, attributeName, options });
   } catch (e) {
     throw new Error(usage);
diff --git a/src/widgets/pagination/pagination.js b/src/widgets/pagination/pagination.js
index b96562f6e9..2fa0e4bdd5 100644
--- a/src/widgets/pagination/pagination.js
+++ b/src/widgets/pagination/pagination.js
@@ -1,6 +1,6 @@
 import defaults from 'lodash/defaults';
 
-import React, { render } from 'preact-compat';
+import React, { render, unmountComponentAtNode } from 'preact-compat';
 import cx from 'classnames';
 
 import Pagination from '../../components/Pagination/Pagination.js';
@@ -177,7 +177,9 @@ export default function pagination(
   });
 
   try {
-    const makeWidget = connectPagination(specializedRenderer);
+    const makeWidget = connectPagination(specializedRenderer, () =>
+      unmountComponentAtNode(containerNode)
+    );
     return makeWidget({ maxPages });
   } catch (e) {
     throw new Error(usage);
diff --git a/src/widgets/price-ranges/price-ranges.js b/src/widgets/price-ranges/price-ranges.js
index 7398f5bc98..ae80e4916a 100644
--- a/src/widgets/price-ranges/price-ranges.js
+++ b/src/widgets/price-ranges/price-ranges.js
@@ -1,4 +1,4 @@
-import React, { render } from 'preact-compat';
+import React, { render, unmountComponentAtNode } from 'preact-compat';
 import cx from 'classnames';
 
 import PriceRanges from '../../components/PriceRanges/PriceRanges.js';
@@ -189,7 +189,9 @@ export default function priceRanges(
   });
 
   try {
-    const makeWidget = connectPriceRanges(specializedRenderer);
+    const makeWidget = connectPriceRanges(specializedRenderer, () =>
+      unmountComponentAtNode(containerNode)
+    );
     return makeWidget({ attributeName });
   } catch (e) {
     throw new Error(usage);
diff --git a/src/widgets/range-slider/range-slider.js b/src/widgets/range-slider/range-slider.js
index 7865a5b968..33a023fd8d 100644
--- a/src/widgets/range-slider/range-slider.js
+++ b/src/widgets/range-slider/range-slider.js
@@ -1,4 +1,4 @@
-import React, { render } from 'preact-compat';
+import React, { render, unmountComponentAtNode } from 'preact-compat';
 import cx from 'classnames';
 
 import Slider from '../../components/Slider/Slider.js';
@@ -204,7 +204,9 @@ export default function rangeSlider(
   });
 
   try {
-    const makeWidget = connectRange(specializedRenderer);
+    const makeWidget = connectRange(specializedRenderer, () =>
+      unmountComponentAtNode(containerNode)
+    );
     return makeWidget({ attributeName, min, max, precision });
   } catch (e) {
     throw new Error(usage);
diff --git a/src/widgets/refinement-list/refinement-list.js b/src/widgets/refinement-list/refinement-list.js
index 139426f366..78e485fe39 100644
--- a/src/widgets/refinement-list/refinement-list.js
+++ b/src/widgets/refinement-list/refinement-list.js
@@ -1,4 +1,4 @@
-import React, { render } from 'preact-compat';
+import React, { render, unmountComponentAtNode } from 'preact-compat';
 import cx from 'classnames';
 import filter from 'lodash/filter';
 
@@ -292,7 +292,9 @@ export default function refinementList(
   });
 
   try {
-    const makeWidget = connectRefinementList(specializedRenderer);
+    const makeWidget = connectRefinementList(specializedRenderer, () =>
+      unmountComponentAtNode(containerNode)
+    );
     return makeWidget({
       attributeName,
       operator,
diff --git a/src/widgets/search-box/search-box.js b/src/widgets/search-box/search-box.js
index 7634bad13e..e789391723 100644
--- a/src/widgets/search-box/search-box.js
+++ b/src/widgets/search-box/search-box.js
@@ -127,6 +127,12 @@ const renderer = ({
   }
 };
 
+const disposer = containerNode => () => {
+  const range = document.createRange(); // IE10+
+  range.selectNodeContents(containerNode);
+  range.deleteContents();
+};
+
 const usage = `Usage:
 searchBox({
   container,
@@ -253,7 +259,10 @@ export default function searchBox(
   });
 
   try {
-    const makeWidget = connectSearchBox(specializedRenderer);
+    const makeWidget = connectSearchBox(
+      specializedRenderer,
+      disposer(containerNode)
+    );
     return makeWidget({ queryHook });
   } catch (e) {
     throw new Error(usage);
diff --git a/src/widgets/sort-by-selector/sort-by-selector.js b/src/widgets/sort-by-selector/sort-by-selector.js
index fc36d851ed..82bd3f613b 100644
--- a/src/widgets/sort-by-selector/sort-by-selector.js
+++ b/src/widgets/sort-by-selector/sort-by-selector.js
@@ -1,4 +1,4 @@
-import React, { render } from 'preact-compat';
+import React, { render, unmountComponentAtNode } from 'preact-compat';
 import cx from 'classnames';
 
 import Selector from '../../components/Selector.js';
@@ -106,7 +106,9 @@ export default function sortBySelector(
   });
 
   try {
-    const makeWidget = connectSortBySelector(specializedRenderer);
+    const makeWidget = connectSortBySelector(specializedRenderer, () =>
+      unmountComponentAtNode(containerNode)
+    );
     return makeWidget({ indices });
   } catch (e) {
     throw new Error(usage);
diff --git a/src/widgets/star-rating/star-rating.js b/src/widgets/star-rating/star-rating.js
index 01270b13e6..128523f188 100644
--- a/src/widgets/star-rating/star-rating.js
+++ b/src/widgets/star-rating/star-rating.js
@@ -1,4 +1,4 @@
-import React, { render } from 'preact-compat';
+import React, { render, unmountComponentAtNode } from 'preact-compat';
 import cx from 'classnames';
 
 import RefinementList from '../../components/RefinementList/RefinementList.js';
@@ -191,7 +191,9 @@ export default function starRating(
   });
 
   try {
-    const makeWidget = connectStarRating(specializedRenderer);
+    const makeWidget = connectStarRating(specializedRenderer, () =>
+      unmountComponentAtNode(containerNode)
+    );
     return makeWidget({ attributeName, max });
   } catch (e) {
     throw new Error(usage);
diff --git a/src/widgets/stats/stats.js b/src/widgets/stats/stats.js
index 946f329c7f..f48ec3a944 100644
--- a/src/widgets/stats/stats.js
+++ b/src/widgets/stats/stats.js
@@ -1,4 +1,4 @@
-import React, { render } from 'preact-compat';
+import React, { render, unmountComponentAtNode } from 'preact-compat';
 import cx from 'classnames';
 
 import Stats from '../../components/Stats/Stats.js';
@@ -166,7 +166,9 @@ export default function stats(
   });
 
   try {
-    const makeWidget = connectStats(specializedRenderer);
+    const makeWidget = connectStats(specializedRenderer, () =>
+      unmountComponentAtNode(containerNode)
+    );
     return makeWidget();
   } catch (e) {
     throw new Error(usage);
diff --git a/src/widgets/toggle/toggle.js b/src/widgets/toggle/toggle.js
index 65ed526e53..7522781a93 100644
--- a/src/widgets/toggle/toggle.js
+++ b/src/widgets/toggle/toggle.js
@@ -1,4 +1,4 @@
-import React, { render } from 'preact-compat';
+import React, { render, unmountComponentAtNode } from 'preact-compat';
 import cx from 'classnames';
 
 import defaultTemplates from './defaultTemplates.js';
@@ -197,7 +197,9 @@ export default function toggle(
   });
 
   try {
-    const makeWidget = connectToggle(specializedRenderer);
+    const makeWidget = connectToggle(specializedRenderer, () =>
+      unmountComponentAtNode(containerNode)
+    );
     return makeWidget({ attributeName, label, values: userValues });
   } catch (e) {
     throw new Error(usage);