Search

grid.search(query, opts?) scans cells, highlights every match, scrolls the first match into view, and emits a search event.

const result = grid.search("error");
console.log(`${result.matches.length} match(es)`); // "2 match(es)"

const result = grid.search("error");
console.log(`${result.matches.length} match(es)`);
grid.findNext();    // advance the active match and scroll to it
grid.clearSearch(); // remove the highlights when done

If cells B2 and D7 contain "error", the log shows 2 match(es). result.matches is [B2, D7] as zero-based addresses, and result.active is 0.

findNext() and findPrev() move the active match. clearSearch() clears the highlights. The built-in Ctrl+F find widget, gated by config.find (on by default), drives this same API.

Options and result

interface SearchOptions {
  matchCase?: boolean; // case-sensitive match (default false)
  wholeCell?: boolean; // match the whole cell, not a substring (default false)
  sheet?: SheetId;     // restrict to one sheet (default: the active sheet)
  columns?: number[];  // restrict to these column indices (default: all)
}

interface SearchResult {
  query: string;
  matches: CellAddress[]; // matching cells, in row-major order
  active: number;         // index of the active match, or -1 when there are none
}

Edge cases and limits

• An active search picks up matches that a value edit adds or removes, without scrolling.
• On sheets with formulas or references, an active search rescans after each edit, including edits to off-screen inputs or other sheets. This keeps matches whose computed text changes.
• highlightCells(ranges, color?) highlights arbitrary ranges independently of search. Pass null to clear; color overrides the theme highlight color. See Temporary highlights.
• Set config.find: false to turn off the Ctrl+F widget. The methods still work.

See also

• Toolbar and ribbon → Feature flags
• Grid methods
• Events
• Generated SearchOptions, SearchResult and ReplaceResult contracts