Filter State and Presets

RevoGrid has two filter-state shapes. Choose the smallest one that represents the query you need:

State	Use it for
MultiFilterItem	Core compatibility, ordinary column controls, and conditions that combine columns with AND
FilterAst	Pro saved views, remote requests, cross-column OR, nested groups, and NOT

MultiFilterItem is runtime-compatible, but some controls use values such as Set. FilterAst is the canonical JSON-safe choice for new persistence and transport integrations.

Set initial column filters

Supply multiFilterItems inside the complete grid filter configuration. Each property is a column property, and each array contains that column’s conditions:

import type { ColumnFilterConfig, MultiFilterItem } from '@revolist/revogrid';

const initialFilters: MultiFilterItem = {
  status: [{ id: 1, type: 'eq', value: 'Open', relation: 'and' }],
  total: [
    { id: 2, type: 'gte', value: 100, relation: 'and' },
    { id: 3, type: 'lte', value: 500, relation: 'and' },
  ],
};

const filterConfig: ColumnFilterConfig = {
  disableDynamicFiltering: false,
  multiFilterItems: initialFilters,
};

grid.filter = filterConfig;

Conditions within one column can use and or or. Different columns in multiFilterItems always combine with AND. Use FilterAst when the query requires cross-column OR, nested groups, or NOT.

Update applied column state

Call the active filter plugin’s onFilterChange() method to replace the complete compatibility model without replacing localization, custom operators, selection settings, or other filter configuration:

import { FilterPlugin, type MultiFilterItem } from '@revolist/revogrid';

const filterPlugin = (await grid.getPlugins()).find(
  (plugin) => plugin instanceof FilterPlugin,
);

const nextFilters: MultiFilterItem = {
  priority: [{ id: 1, type: 'eq', value: 'High', relation: 'and' }],
};

await filterPlugin?.onFilterChange(nextFilters);

AdvanceFilterPlugin extends Core’s FilterPlugin, so the same lookup works when Pro filtering is installed. Passing {} removes all column conditions.

Use afterfilterapply to observe the applied compatibility state:

import type { MultiFilterItem } from '@revolist/revogrid';

grid.addEventListener('afterfilterapply', (event) => {
  const detail = (event as CustomEvent<{ multiFilterItems: MultiFilterItem }>)
    .detail;
  const appliedFilters = detail.multiFilterItems;
  console.log(appliedFilters);
});

Create reusable presets

A preset can be a MultiFilterItem, but reassigning grid.filter with only that object would drop the rest of the configuration. Keep one factory that recreates every option:

import type { ColumnFilterConfig, MultiFilterItem } from '@revolist/revogrid';

function createFilterConfig(
  multiFilterItems: MultiFilterItem = {},
): ColumnFilterConfig {
  return {
    allowDuplicateOperators: true,
    disableDynamicFiltering: false,
    localization: {
      captions: {
        save: 'Apply',
        reset: 'Reset',
      },
    },
    multiFilterItems,
  };
}

const presets: Record<string, MultiFilterItem> = {
  openHighValue: {
    status: [{ id: 101, type: 'eq', value: 'Open', relation: 'and' }],
    total: [{ id: 102, type: 'gte', value: 1000, relation: 'and' }],
  },
  needsReview: {
    status: [
      { id: 201, type: 'eq', value: 'Pending', relation: 'or' },
      { id: 202, type: 'eq', value: 'On Hold', relation: 'or' },
    ],
  },
};

function applyPreset(name: keyof typeof presets) {
  grid.filter = createFilterConfig(presets[name]);
}

function clearPreset() {
  grid.filter = createFilterConfig({});
}

When the grid is already initialized, onFilterChange(presets[name]) is usually simpler because it preserves the active configuration without recreating it.

Save and restore canonical state

For new saved-view and backend integrations, use Pro’s JSON-safe FilterAst. Register AdvanceFilterPlugin, read a defensive clone with getFilterAst(), and restore it atomically with setFilterAst():

import { AdvanceFilterPlugin, type FilterAst } from '@revolist/revogrid-pro';

grid.plugins = [AdvanceFilterPlugin];

const plugin = (await grid.getPlugins()).find(
  (item) => item instanceof AdvanceFilterPlugin,
) as AdvanceFilterPlugin | undefined;

function saveView(storageKey: string) {
  const ast = plugin?.getFilterAst();
  if (ast) {
    localStorage.setItem(storageKey, JSON.stringify(ast));
  } else {
    localStorage.removeItem(storageKey);
  }
}

async function restoreView(storageKey: string) {
  const saved = localStorage.getItem(storageKey);
  const ast = saved ? (JSON.parse(saved) as FilterAst) : undefined;
  await plugin?.setFilterAst(ast);
}

setFilterAst() validates the whole tree before applying it. Invalid state rejects without replacing the previous valid filter. Passing undefined clears filtering. You can also set initial canonical state with grid.filter = { filterAst }; when initial filterAst, multiFilterItems, and the legacy collection are supplied together, filterAst takes precedence.

The canonical tree represents conditions, groups, and negation with JSON values. Do not put Date, Set, functions, cycles, or non-finite numbers in a public AST.

Compatibility state and JSON

Do not send MultiFilterItem directly through JSON.stringify() without checking its values. For example, the selection filter stores excluded checklist values in a Set, and JSON serializes a Set as {}.

const compatibilityState = {
  status: [
    {
      id: 1,
      type: 'selection',
      value: new Set(['archived']),
      relation: 'and',
    },
  ],
};

Pro exports compatibility transport helpers that convert values such as Set and Date to JSON-friendly arrays and ISO strings. They are useful when maintaining an existing MultiFilterItem integration, but the compatibility format spans filter-specific runtime contracts. Do not assume those helpers provide a lossless saved-view format for every current or future Pro operator. Prefer getFilterAst() for new persistence and remote-filter payloads.

Clear all filter state

Clear through the plugin so configuration stays installed:

import { FilterPlugin } from '@revolist/revogrid';

const filterPlugin = (await grid.getPlugins()).find(
  (plugin) => plugin instanceof FilterPlugin,
);

await filterPlugin?.clearFiltering();

With AdvanceFilterPlugin, clearFiltering() also clears quick-filter and canonical AST state. await plugin.setFilterAst(undefined) is the equivalent canonical operation and also clears the quick filter.

Common mistakes

• Assigning grid.filter = { multiFilterItems } after configuring localization, custom filters, selection options, or structured filter types. Use onFilterChange() or recreate the complete configuration with a factory.
• Treating multiFilterItems as cross-column Boolean logic. Different columns combine with AND; use FilterAst for cross-column OR and nested groups.
• Mutating a previously applied object and expecting a reactive update. Create the next state and pass it to onFilterChange() or setFilterAst().
• Serializing selection-filter Set values directly. Use canonical FilterAst for new saved views.
• Restoring untrusted JSON without handling rejection from setFilterAst().
• Clearing state by disabling grid.filter. Call clearFiltering() to keep filtering installed and configured.

Related guides

• Filtering Quick Start
• Canonical Filter AST
• Filter Events
• Selection Filter
• Advanced Filtering Overview