# AdapTable Quick Search

Canonical page: https://www.adaptabletools.com/docs/handbook-quick-search

- Quick Search finds and **highlights** matching text across visible cells in the Grid
- It searches cell **display values** by default (not numeric filters or AdapTableQL)
- Matching text uses configurable [Matching Styles](https://www.adaptabletools.com/docs/handbook-quick-search-matching-styles/index.md); optionally you can [filter rows](https://www.adaptabletools.com/docs/handbook-quick-search-as-filter/index.md) to matching results only
- Search inputs appear on the [Dashboard](https://www.adaptabletools.com/docs/ui-dashboard/index.md), [Status Bar](https://www.adaptabletools.com/docs/ui-status-bar/index.md), [Tool Panel](https://www.adaptabletools.com/docs/ui-tool-panel/index.md), and elsewhere

AdapTable provides a cross-grid **text search** called Quick Search.

AdapTable finds and highlights all instances of the search text in:

- All AG Grid data / field columns
- Dynamic columns (e.g. row grouped or tree view columns)
- AdapTable special columns (e.g. [Calculated](https://www.adaptabletools.com/docs/handbook-calculated-column/index.md) and [FreeText](https://www.adaptabletools.com/docs/handbook-freetext-column/index.md) columns)
- Leaf (data) rows
- Grouped rows (i.e. rows that contain aggregations)

- For row-level filtering with expressions, use [Grid Filter](https://www.adaptabletools.com/docs/handbook-grid-filter/index.md) or [Column Filters](https://www.adaptabletools.com/docs/handbook-column-filter/index.md) instead
- They hide non-matching **rows**, not just highlight cells

Unlike those filters, Quick Search is **purely text-based** and runs on each cell's **display value**.

For example, a cell with a display value of `£1,500` will not match a search for `1500` (but `£1` will match).

- Cells using an AG Grid [cell component](https://www.ag-grid.com/javascript-data-grid/cell-rendering/) are searched using the **raw** value 
- This is because the cell may be showing an image or custom renderer output

### How Quick Search Works in AdapTable

When Quick Search runs, AdapTable evaluates the **display value** of every visible cell (see [Configuring Quick Search](https://www.adaptabletools.com/docs/handbook-quick-search-configuring/index.md) for raw-value search, bespoke matching, or excluding cells) and highlights cells that contain the search text.

Matching text uses the configured [Matching Styles](https://www.adaptabletools.com/docs/handbook-quick-search-matching-styles/index.md).

Behaviour depends on the AG Grid row model:

- **Client-Side Row Model** — Quick Search wraps [AG Grid Find](https://www.ag-grid.com/javascript-data-grid/find/). AdapTable supplies the run-time UI; AG Grid Find performs in-cell highlighting and supports **cycling** through matches. Register AG Grid's `FindModule` (see [AG Grid Modules](https://www.adaptabletools.com/docs/getting-started-aggrid-modules/index.md)).
- **Server-Side Row Model** — AG Grid Find is not available, so AdapTable uses a [bespoke implementation](https://www.adaptabletools.com/docs/dev-guide-row-models-server-searching/index.md) (whole-cell highlight only; no match cycling).

Quick Search inputs are **debounced by 350ms** so the search runs when typing pauses, not on every keystroke.

**Example: Quick Search**

Running Quick Search in AdapTable

- Initial State runs Quick Search for **`Java`** — cells whose display text contains that substring are highlighted (e.g. **JavaScript** in the `language` column)
- The Dashboard header and Status Bar both include a Quick Search input; change the text to try other terms

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts        [template]
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {AdaptableOptions} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Basic Quick Search',
  notificationsOptions: {
    duration: 'always',
  },
  customSortOptions: {
    customSortComparers: [
      {
        name: 'Comparer-date',
        scope: {
          DataTypes: ['date'],
        },
        comparer: (valueA: any, valueB: any) => {
          const date1 = new Date(valueA);
          const date2 = new Date(valueB);
          if (date1 > date2) {
            return -1;
          }
          if (date1 < date2) {
            return 1;
          }
          return 0;
        },
      },
    ],
  },
  initialState: {
    Dashboard: {
      ModuleButtons: ['QuickSearch'],
    },
    QuickSearch: {
      QuickSearchText: 'Java',
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['QuickSearch'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'topics',
            'license',
            'description',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'github_watchers',
            'open_issues_count',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

- Quick Search **re-runs** when the search text changes, when grid data is edited, or when column visibility changes
- The active search text is stored as `QuickSearchText` in [Quick Search Initial State](https://www.adaptabletools.com/docs/technical-reference-quick-search/index.md)

## Topics in this Section

<section className="my-8 sm:my-10 grid grid-cols-1 lg:grid-cols-2 gap-x-8 gap-y-4">
  <div className="flex flex-col justify-center">
    
  </div>
  <div className="flex flex-col justify-center">
    
  </div>
  <div className="flex flex-col justify-center">
    
  </div>
  <div className="flex flex-col justify-center">
    
  </div>
</section>

## Quick Search inputs

Quick Search is available in several places so users can search without opening a module popup:

| Location                                                                       | Notes                                                                                                                                                                                        |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Dashboard Header](https://www.adaptabletools.com/docs/ui-dashboard/index.md)                    | Shown by default in Expanded, Collapsed, and Floating modes<br />Hide with `showQuickSearchInHeader: false` in [Dashboard Options](https://www.adaptabletools.com/docs/technical-reference-dashboard/index.md) |
| [Settings Panel](https://www.adaptabletools.com/docs/ui-settings-panel/index.md)                 | Run search and configure [matching styles](https://www.adaptabletools.com/docs/handbook-quick-search-matching-styles/index.md) (Filter Quick Search Results if enabled)                                        |
| [Dashboard Toolbar](https://www.adaptabletools.com/docs/ui-dashboard/index.md#tabs-and-toolbars) | Rarely used because the header already contains an input                                                                                                                                     |
| [Tool Panel](https://www.adaptabletools.com/docs/ui-tool-panel/index.md)                         | Quick Search Module Tool Panel                                                                                                                                                               |
| [Status Bar](https://www.adaptabletools.com/docs/ui-status-bar/index.md)                         | Optional `QuickSearch` status bar panel                                                                                                                                                      |

- The default placeholder text is `Search`
- Set `quickSearchPlaceholder` in [Quick Search Options](https://www.adaptabletools.com/docs/technical-reference-quick-search/index.md) to customise it — see [Configuring Quick Search](https://www.adaptabletools.com/docs/handbook-quick-search-configuring/index.md)

## Cycling through matches

Users can move between matches using the **up / down** controls on Quick Search inputs.

This is also available programmatically via `gotoNextMatch` / `gotoPreviousMatch` on the [Quick Search API](https://www.adaptabletools.com/docs/technical-reference-quick-search/index.md)

The **current** match uses `CurrentTextMatchStyle`.

- Match cycling is **not** available with the [Server-Side Row Model](https://www.adaptabletools.com/docs/dev-guide-row-models-server-searching/index.md) implementation
- Nor when using a [bespoke Quick Search](https://www.adaptabletools.com/docs/handbook-quick-search-configuring/index.md) via `getCellSearchText` (whole-cell `CellMatchStyle` only)

## Matching cell styles

When Quick Search runs, matching cells are styled so results stand out.

Three styles are stored in Quick Search State (each an [Adaptable Style](https://www.adaptabletools.com/docs/ui-tutorial-providing-adaptable-style/index.md)):

- `CellMatchStyle` — styles **all text** in matching cells (optional until enabled in the UI)
- `TextMatchStyle` — styles **matching substring** within the cell
- `CurrentTextMatchStyle` — styles the current match when **cycling** through results

See [Quick Search Matching Styles](https://www.adaptabletools.com/docs/handbook-quick-search-matching-styles/index.md) for defaults, theme variables, design-time State, and Settings Panel tabs.

## Configuration options

All Quick Search options live on `quickSearchOptions` in [Adaptable Options](https://www.adaptabletools.com/docs/technical-reference-adaptable-options/index.md):

| Option                                        | Purpose                                                                            |
| --------------------------------------------- | ---------------------------------------------------------------------------------- |
| `getCellSearchText`                           | Text to search per cell (raw value, bespoke matching, comma-separated terms, etc.) |
| `isCellSearchable`                            | Exclude specific columns or cells from search                                      |
| `isQuickSearchCaseSensitive` | Match search text with exact casing                                                |
| `quickSearchPlaceholder`                      | Placeholder string for Quick Search inputs                                         |
| `clearQuickSearchOnStartUp`                   | Do not restore saved `QuickSearchText` on load                                     |
| `filterGridAfterQuickSearch`                  | Also hide rows with no matches (AG Grid Quick Filter)                              |

See [Configuring Quick Search](https://www.adaptabletools.com/docs/handbook-quick-search-configuring/index.md) and [Filtering Quick Search Results](https://www.adaptabletools.com/docs/handbook-quick-search-as-filter/index.md) for further details and demo examples

## Filter Search Results

By default Quick Search **highlights** matches only; all rows remain visible.

Set `filterGridAfterQuickSearch` to _true_ (or enable 'Filter Quick Search Results' in the Settings Panel) to show only rows that contain the search text in at least one visible, searchable column.

This uses AG Grid's [Quick Filter](https://www.ag-grid.com/javascript-data-grid/filter-quick/) — register AG Grid's `QuickFilterModule` when using this option.

- Quick Search as Filter does not use [AdapTableQL](https://www.adaptabletools.com/docs/adaptable-ql-expression/index.md); it ignores `getCellSearchText` / `isCellSearchable` exclusions
- Prefer [Column Filters](https://www.adaptabletools.com/docs/handbook-column-filter/index.md) or [Grid Filter](https://www.adaptabletools.com/docs/handbook-grid-filter/index.md) for large grids or expression-based filtering

See [Filtering Quick Search Results](https://www.adaptabletools.com/docs/handbook-quick-search-as-filter/index.md) for performance notes, SSRM behaviour, and customising `quickFilterParser`.

## Server-Side Row Model

Quick Search works fully when using the [Server-Side Row Model](https://www.adaptabletools.com/docs/dev-guide-row-models-server-overview/index.md).

However, AdapTable uses its own search implementation instead of AG Grid Find.

- Highlights apply to rows as they load; newly fetched rows are searched when they appear.
- Only **`CellMatchStyle`** applies (whole-cell highlight).
- **Cycling** through matches is not supported.

See [Server-Side Row Model - Searching](https://www.adaptabletools.com/docs/dev-guide-row-models-server-searching/index.md) for a demo and implementation notes.

## UI Entitlements

[UI Entitlements](https://www.adaptabletools.com/docs/handbook-permissioning/index.md) for the Quick Search module:

- **`Full`** — Quick Search runs normally and all Quick Search UI controls are available.
- **`Hidden`** and **`ReadOnly`** — module UI (Settings Panel, Toolbar, Tool Panel, Status Bar) is not available.

- The Dashboard header Quick Search input can still appear when the module is **`ReadOnly`**
- Set `showQuickSearchInHeader` to *false* in [Dashboard Options](https://www.adaptabletools.com/docs/technical-reference-dashboard/index.md) to hide it

## Quick Search API

Quick Search can be driven programmatically via the [Quick Search API](https://www.adaptabletools.com/docs/technical-reference-quick-search/index.md):

- run or clear search — `runQuickSearch`, `clearQuickSearch`
- read current text — `getQuickSearchValue`
- cycle matches (client-side Find) — `gotoNextMatch`, `gotoPreviousMatch`
- matching styles — get/set style properties
- floating search — `showFloatingQuickSearch`, `hideFloatingQuickSearch`
- Settings Panel — `openQuickSearchSettingsPanel`

### FAQ

**Does Quick Search update when data changes?**
Yes. Like [Grid Filter](https://www.adaptabletools.com/docs/handbook-grid-filter/index.md) and [Column Filters](https://www.adaptabletools.com/docs/handbook-column-filter/index.md), an active Quick Search is reapplied when data changes.

**Does Quick Search run on grouped rows?**
Yes. Quick Search evaluates grouped rows (including aggregations) as well as leaf data rows.

**Can users type expressions (e.g. `> 50`) in Quick Search?**
No. Quick Search is substring text search on display (or configured) cell text. Use [Column Filters](https://www.adaptabletools.com/docs/handbook-column-filter/index.md) or [Grid Filter](https://www.adaptabletools.com/docs/handbook-grid-filter/index.md) for structured filtering.

**Which AG Grid modules does Quick Search need?**
Client-side highlighting requires AG Grid **`FindModule`**. If you enable `filterGridAfterQuickSearch`, also register **`QuickFilterModule`** (see [AG Grid Modules](https://www.adaptabletools.com/docs/getting-started-aggrid-modules/index.md)).
