diff --git a/addons/addon-search/README.md b/addons/addon-search/README.md
index fab0b03f5..6b9a575b1 100644
--- a/addons/addon-search/README.md
+++ b/addons/addon-search/README.md
@@ -20,4 +20,11 @@ terminal.loadAddon(searchAddon);
 searchAddon.findNext('foo');
 ```
 
+### Search options
+
+- `decorations`: Highlight all matches and fire `onDidChangeResults` with result counts.
+- `highlightLimit` (constructor option): Caps how many matches are tracked/highlighted (default `1000`).
+- `incremental`: Expands the current selection when the term still matches.
+- `wholeWord`, `regex`, `caseSensitive`: Control match semantics.
+
 See the full [API](https://github.com/xtermjs/xterm.js/blob/master/addons/addon-search/typings/addon-search.d.ts) for more advanced usage.
diff --git a/addons/addon-search/typings/addon-search.d.ts b/addons/addon-search/typings/addon-search.d.ts
index 40034da9a..5541a3df5 100644
--- a/addons/addon-search/typings/addon-search.d.ts
+++ b/addons/addon-search/typings/addon-search.d.ts
@@ -28,8 +28,7 @@ declare module '@xterm/addon-search' {
 
     /**
      * Whether to do an incremental search, this will expand the selection if it
-     * still matches the term the user typed. Note that this only affects
-     * `findNext`, not `findPrevious`.
+     * still matches the term the user typed.
      */
     incremental?: boolean;
 
@@ -57,7 +56,7 @@ declare module '@xterm/addon-search' {
     /**
      * The overview ruler color of a match.
      */
-    matchOverviewRuler: string;
+    matchOverviewRuler?: string;
 
     /**
      * The background color for the currently active match, this must use #RRGGBB format.
@@ -72,7 +71,7 @@ declare module '@xterm/addon-search' {
     /**
      * The overview ruler color of the currently active match.
      */
-    activeMatchColorOverviewRuler: string;
+    activeMatchColorOverviewRuler?: string;
   }
 
   /**
@@ -80,12 +79,13 @@ declare module '@xterm/addon-search' {
    */
   export interface ISearchResultChangeEvent {
     /**
-     * The index of the currently active result, -1 when the threshold of matches is exceeded.
+     * The index of the currently active result within tracked highlights, or -1 when
+     * the active match is not in the tracked result set.
      */
     resultIndex: number;
 
     /**
-     * The total number of search results found.
+     * The number of tracked search results (capped by `highlightLimit` when decorations are enabled).
      */
     resultCount: number;
   }
@@ -96,9 +96,9 @@ declare module '@xterm/addon-search' {
   export interface ISearchAddonOptions {
     /**
      * Max number of matches highlighted when decorations are enabled.
-     * Defaults to 1000 highlighted matches
+     * Defaults to 1000. Invalid values fall back to the default.
      */
-    highlightLimit: number
+    highlightLimit?: number;
   }
 
   /**
@@ -140,7 +140,7 @@ declare module '@xterm/addon-search' {
     public findPrevious(term: string, searchOptions?: ISearchOptions): boolean;
 
     /**
-     * Clears the decorations and selection
+     * Clears highlight decorations and tracked results.
      */
     public clearDecorations(): void;