Resolve #751/#773

README.md

@@ -824,12 +824,6 @@ choices.setValue(['Set value 1', 'Set value 2']);
 choices.disable();
 ```
 
-### destroy();
-
-**Input types affected:** `text`, `select-multiple`, `select-one`
-
-**Usage:** Kills the instance of Choices, removes all event listeners and returns passed input to its initial state.
-
 ### init();
 
 **Input types affected:** `text`, `select-multiple`, `select-one`
@@ -838,6 +832,12 @@ choices.disable();
 
 **Note:** This is called implicitly when a new instance of Choices is created. This would be used after a Choices instance had already been destroyed (using `destroy()`).
 
+### destroy();
+
+**Input types affected:** `text`, `select-multiple`, `select-one`
+
+**Usage:** Kills the instance of Choices, removes all event listeners and returns passed input to its initial state.
+
 ### highlightAll();
 
 **Input types affected:** `text`, `select-multiple`
@@ -880,7 +880,7 @@ choices.disable();
 
 **Usage:** Hide option list dropdown (only affects select inputs).
 
-### setChoices(choices, value, label, replaceChoices);
+### setChoices(choices[, value[, label[, replaceChoices]]]);
 
 **Input types affected:** `select-one`, `select-multiple`
 
@@ -966,7 +966,13 @@ example.setChoices(
 
 **Input types affected:** `select-one`, `select-multiple`
 
-**Usage:** Clear all choices from select
+**Usage:** Clear all choices
+
+### clearItems();
+
+**Input types affected:** `text`, `select-one`, `select-multiple`
+
+**Usage:** Clear all items
 
 ### getValue(valueOnly)
 

src/scripts/actions/items.js

@@ -51,3 +51,10 @@ export const highlightItem = (id, highlighted) => ({
   id,
   highlighted,
 });
+
+/**
+ * @returns {Action}
+ */
+export const clearItems = () => ({
+  type: ACTION_TYPES.CLEAR_ITEMS,
+});

src/scripts/actions/items.test.js

@@ -68,4 +68,14 @@ describe('actions/items', () => {
       expect(actions.highlightItem(id, highlighted)).to.eql(expectedAction);
     });
   });
+
+  describe('clearItems action', () => {
+    it('returns CLEAR_ITEMS action', () => {
+      const expectedAction = {
+        type: 'CLEAR_ITEMS',
+      };
+
+      expect(actions.clearItems()).to.eql(expectedAction);
+    });
+  });
 });

src/scripts/choices.js

@@ -25,7 +25,12 @@ import {
   activateChoices,
   clearChoices,
 } from './actions/choices';
-import { addItem, removeItem, highlightItem } from './actions/items';
+import {
+  addItem,
+  removeItem,
+  highlightItem,
+  clearItems,
+} from './actions/items';
 import { addGroup } from './actions/groups';
 import { clearAll, resetTo, setIsLoading } from './actions/misc';
 import {
@@ -496,7 +501,7 @@ class Choices {
    * @param {T} [choicesArrayOrFetcher]
    * @param {string} [value = 'value'] - name of `value` field
    * @param {string} [label = 'label'] - name of 'label' field
-   * @param {boolean} [replaceChoices = false] - whether to replace of add choices
+   * @param {boolean} [replaceChoices = false] - whether to clear existing choices
    * @returns {this | Promise<this>}
    *
    * @example
@@ -574,9 +579,9 @@ class Choices {
       );
     }
 
-    // Clear choices if needed
     if (replaceChoices) {
       this.clearChoices();
+      this.clearItems();
     }
 
     if (typeof choicesArrayOrFetcher === 'function') {
@@ -651,6 +656,12 @@ class Choices {
     return this;
   }
 
+  clearItems() {
+    this._store.dispatch(clearItems());
+
+    return this;
+  }
+
   clearStore() {
     this._store.dispatch(clearAll());