diff --git a/docs/api/events.md b/docs/api/events.md
index ae83772..a314206 100644
--- a/docs/api/events.md
+++ b/docs/api/events.md
@@ -4,7 +4,7 @@ Triggered when the selected value changes. Used internally for `v-model`.
 
 ```js
 /**
- * @param val {Object|String}` - selected option.
+ * @param {Object|String} val - selected option.
  */
 this.$emit("input", val);
 ```
@@ -63,11 +63,40 @@ Triggered when `taggable` is `true` and a new option has been created.
 
 ```js
 /**
- * @param newOption {Object} - created option
+ * @param {Object} newOption - created option
  */
 this.$emit("option:created", newOption);
 ```
 
+## `search`
+
+Anytime the search string changes, emit the
+'search' event. The event is passed with two 
+parameters: the search string, and a function 
+that accepts a boolean parameter to toggle the 
+loading state.
+
+See the [AJAX Guide](/guide/ajax.html#loading-options-with-ajax) 
+for a complete example.
+
+```js
+/**
+ * @param {String} searchString - the search string
+ * @param {Function} toggleLoading - function to toggle loading state, accepts true or false boolean
+ */
+this.$emit('search', this.search, this.toggleLoading);
+```
+
+```vue
+<!-- example usage -->
+<v-select
+    @search="(search, loading) => { 
+      loading(true)
+      fetchOptions(search).then(() => loading(false))
+    }"
+/>
+```
+
 ## `search:blur`
 
 Triggered when the text input loses focus. The dropdown will close immediately before this