Quick Filter

Quick Filter is RevoGrid Pro’s global row search. Use it for a toolbar search box that should look across several columns without creating one filter condition per field.

Source code

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  { prop: 'customer', name: 'Customer' },
  { prop: 'city', name: 'City' },
  { prop: 'status', name: 'Status' },
];
grid.filter = true;

return [
  { customer: 'Ana Silva', city: 'Lisbon', status: 'Pending' },
  { customer: 'Marco Costa', city: 'Lisbon', status: 'Complete' },
  { customer: 'Beatriz Sousa', city: 'Porto', status: 'Pending' },
  { customer: 'Tiago Santos', city: 'Coimbra', status: 'Complete' },
];

Quick start

1
import { AdvanceFilterPlugin } from '@revolist/revogrid-pro';
2
import '@revolist/revogrid-pro/dist/revogrid-pro.css';
3

4
grid.plugins = [AdvanceFilterPlugin];
5
grid.columns = [
6
  { prop: 'customer', name: 'Customer' },
7
  { prop: 'city', name: 'City' },
8
  { prop: 'status', name: 'Status', filter: 'string' },
9
];
10
grid.filter = true;
11

12
grid.quickFilter = 'Lisbon pending';

The direct quickFilter property is preferred. The older additionalData.quickFilter path remains available for compatibility.

String and object forms

Use a string for the default 150 ms debounce and all visible regular data columns:

1
grid.quickFilter = 'Lisbon pending';

Use the object form to choose exact column properties or change the debounce:

1
grid.quickFilter = {
2
  text: 'Lisbon pending',
3
  columns: ['city', 'status'],
4
  debounceMs: 250,
5
};

Field	Default	Behavior
`text`	Required	Trimmed and collapsed to single spaces
`columns`	Visible regular data columns	Exact, duplicate-free property list
`debounceMs`	`150`	Finite values are clamped to at least `0`

Omitting columns searches visible regular columns. Providing columns: [] deliberately searches no fields and therefore matches no row while the query contains a token.

How tokens match

Search is case-insensitive. Normalized text is split on spaces, and every token must appear in at least one searched column. Different tokens may match different columns in the same row.

For example, Lisbon pending matches a row when Lisbon appears in its city and pending appears in its status. This is equivalent to:

1
(customer contains Lisbon OR city contains Lisbon OR status contains Lisbon)
2
AND
3
(customer contains pending OR city contains pending OR status contains pending)

Quick Filter reads parsed cell values. A column cellParser or Pro value-resolution hook therefore affects both global search and advanced filter option values. Dropdown columns are searched by their visible option labels, including every label in a multi-select value, even when the row stores option IDs through valueKey.

Clear the search

Assign an empty or whitespace-only string:

1
grid.quickFilter = '';

Whitespace normalization means ' ' also clears the active quick filter.

Observe or intercept changes

Quick-filter changes emit a cancelable event before filtering and a completion event afterward:

1
grid.addEventListener('beforequickfilterapply', (event) => {
2
  console.log('Applying', event.detail.quickFilter);
3
});
4

5
grid.addEventListener('afterquickfilterapply', async (event) => {
6
  const visibleRows = await grid.getVisibleSource();
7
  console.log('Applied', event.detail.quickFilter, visibleRows.length);
8
});

Both event details contain the normalized quickFilter, current source, and columns. Clearing emits the same events with quickFilter set to undefined. If beforequickfilterapply is prevented, local filtering and afterquickfilterapply do not run.

Combine with column filters

Quick Filter is ANDed with active column conditions and the canonical Filter AST:

1
grid.filter = {
2
  multiFilterItems: {
3
    amount: [{ id: 1, type: 'gte', value: 200, relation: 'and' }],
4
  },
5
};
6
grid.quickFilter = 'Lisbon pending';

A row must satisfy the amount condition and every quick-filter token. Quick Filter does not add a synthetic column entry to multiFilterItems; Pro composes it into the effective FilterAst with quickContains conditions.

Remote data

The Pro Pagination, Infinity Scroll, and Server-Side Grouping plugins intercept beforequickfilterapply, prevent local filtering, and pass the normalized quick filter to their remote loaders. Pagination and Infinity Scroll receive it as the optional sixth loadData argument. They emit afterquickfilterapply only after the winning remote request updates the source.

For a custom remote adapter, prevent beforequickfilterapply, cancel or ignore stale requests, send event.detail.quickFilter to the backend, replace grid.source, and emit a completion signal only for the latest response.

Common mistakes

Do not expect columns: [] to mean all columns; omit columns for the default search set.
Do not split the query yourself. RevoGrid normalizes whitespace and applies its AND-across-tokens semantics.
Do not expect each token to match the same column; tokens may match different fields in one row.
Do not read event.detail.source as the filtered result. Use getVisibleSource() after local completion.
Do not use the deprecated additionalData.quickFilter path in new code.