diff --git a/docs/api.md b/docs/api.md
index 1a9704c5c..83300445f 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -397,6 +397,27 @@ var argv = require('yargs/yargs')(process.argv.slice(2))
   .argv;
 ```
 
+Using default completions in a custom implementation. When invoked with no arguments, `completionFilter` will fallback to the default completion function. There is no need to call `done` in this case. When provided with a callback function, you can get access to `defaultCompletions` and call `done` with your processed version of them.
+
+```js
+var argv = require('yargs/yargs')(process.argv.slice(2))
+  .completion('completion', function(current, argv, completionFilter, done) {
+    // if 'apple' present return default completions
+    if (argv._.includes('apple')) {
+      completionFilter();
+    } else {
+      completionFilter((err, defaultCompletions) => {
+        const filteredCompletions = defaultCompletions.filter(
+          completion => !completion.includes('banana'),
+        );
+        // else return default completions w/o 'banana'
+        done(filteredCompletions);
+      });
+    }
+  })
+  .argv;
+```
+
 <a name="config"></a>.config([key], [description], [parseFn])
 -------------------------------------------------------------
 .config(object)