Guide to Filtering

Filter Technical Reference

View as Markdown

Filter Options

FilterOptions

Column Filters (one column) and the Grid Filter (a query across columns).

The filters a user creates are stored on the Layout. These options change how filtering works for the whole grid.

clearFiltersOnStartUp?

boolean

Clear Grid and Column Filters when AdapTable loads

Default

false

columnFilterOptions?

ColumnFilterOptions

The filter row under the column headers, and the operator offered first for each data type.

customInFilterValues?

(context:CustomInFilterValuesContext<TData>) => Promise<InFilterValueResult> |InFilterValueResult

Provide custom values (or sorting / count info) when using the IN operator in Column or Grid Filter

enableFilterOnSpecialColumns?

boolean

Allow filtering on Calculated & FreeText columns

Default

true

isRowFilterable?

(context:IsRowFilterableContext) => boolean

Configures whether Rows will be evaluated when filtering

showDatePicker?

boolean

Show Date Picker (or Date Input) in Filter controls

Default

true

useAdaptableFiltering?

boolean

Use Adaptable's Column & Grid Filters in preference to AG Grid's filtering

Default

true

Column Filter Options

ColumnFilterOptions

Options for managing Column Filtering in AdapTable

defaultArrayColumnFilter?

DefaultArrayColumnFilter| ((adaptableColumnContext:DefaultFilterExpressionContext) =>DefaultArrayColumnFilter)

Default filter operator for array Columns ('textArray', 'numberArray', etc.)

Default

IN

defaultDateColumnFilter?

DefaultDateColumnFilter| ((adaptableColumnContext:DefaultFilterExpressionContext) =>DefaultDateColumnFilter)

Default filter operator for date Columns.

'IS_SAME_DAY' matches the same calendar day. Use 'EQ' when you need
exact timestamp equality.

Default

IS_SAME_DAY

defaultNumericColumnFilter?

DefaultNumericColumnFilter| ((adaptableColumnContext:DefaultFilterExpressionContext) =>DefaultNumericColumnFilter)

Default filter operator for numeric Columns

Default

EQ

defaultTextColumnFilter?

DefaultTextColumnFilter| ((adaptableColumnContext:DefaultFilterExpressionContext) =>DefaultTextColumnFilter)

Default filter operator for text Columns

Default

CONTAINS

hideQuickFilterDropdown?

(adaptableColumnContext:AdaptableColumnContext<TData>) => boolean

Hides Dropdown in Quick Filter Bar for a given Column

Default

undefined

indicateFilteredColumns?

boolean

Make Column Header distinctive for filtered columns, helps users see currently filtered columns

Default

true

manuallyApplyColumnFilter?

boolean | ((context:AdaptableColumnContext) => boolean)

Manually apply Column Filters; an Apply Filter button is displayed and Quick Filter is disabled

Default

false

quickFilterDebounce?

number

Time to wait (in ms) before Filter Bar reacts to new value

Default

250

quickFilterHeight?

number

Height of Quick Filter Bar (if not provided, AG Grid default is used)

Default

null

quickFilterWildcards?

Partial<Record<ColumnFilterOperator, string[]>>

Shortcut keystrokes that activate a Quick Filter operator, keyed by the
AQL operator name (e.g. { GT: ['>'], IN: ['#', '['] }).

showQuickFilter?

boolean

Display Quick Filter Bar between Column Header and Grid (provided its been setup)

Default

true

defaultTextColumnFilter is a DefaultTextColumnFilter:

Value
'EQ'
'NEQ'
'CONTAINS'
'NOT_CONTAINS'
'STARTS_WITH'
'ENDS_WITH'
'REGEX'
'IN'
'NOT_IN'
'IS_BLANK'
'IS_NOT_BLANK'

defaultNumericColumnFilter is a DefaultNumericColumnFilter:

Value
'EQ'
'NEQ'
'GT'
'GTE'
'LT'
'LTE'
'IN'
'NOT_IN'
'IS_BLANK'
'IS_NOT_BLANK'

defaultDateColumnFilter is a DefaultDateColumnFilter:

Value
'EQ'
'NEQ'
'GT'
'GTE'
'LT'
'LTE'
'IS_SAME_DAY'
'IS_DIFFERENT_DAY'
'IN'
'NOT_IN'
'IS_BLANK'
'IS_NOT_BLANK'

defaultArrayColumnFilter is a DefaultArrayColumnFilter:

Value
'IN'
'NOT_IN'
'IS_BLANK'
'IS_NOT_BLANK'

quickFilterWildcards entries are a ColumnFilterOperator:

Value
'EQ'
'NEQ'
'LT'
'LTE'
'GT'
'GTE'
'IN'

customInFilterValues receives a CustomInFilterValuesContext and returns an InFilterValueResult:

CustomInFilterValuesContext

Context used when providing values for the IN Column Filter

Extends

AdaptableColumnContext

currentSearchValue

string

Current text in the IN Filter search box.

Useful when implementing server-side filtering of the value list.

defaultValues

ComputedInFilterValueInfo[]

Distinct Column values in natural (unsorted) row iteration order.

When the Column uses a Tree Filter, items have a hierarchical structure.

Computed lazily on first access.

limit

number

Suggested page size. Consumers may return fewer or more items. Useful when hasMore is true on the return object (lazy pagination).

Default

1000

offset

number

Zero-based index of the first value to return.
Reset to 0 when the dropdown opens or currentSearchValue changes.
Increased when loading the next page (hasMore is true on the return object - this means lazy pagination is enabled).

Default

0

orderedValues

ComputedInFilterValueInfo[]

Distinct Column values in the order they appear in the grid from top to bottom.

Always a flat list, even when the Column uses a Tree Filter.

Computed lazily on first access.

previousFilterResult?

InFilterValueResult

The result returned by the previous invocation of FilterOptions.customInFilterValues, if any.

Useful for avoiding expensive recomputations (e.g. when filtering is async or server-side).
Opaque pagination cursors may also be stashed on this object and read on the next call.

selectedValues

InFilterValue[]

Values currently selected in the IN (or NOT IN) Column Filter.

Labels are resolved from previously loaded In Filter items when available.

Useful with lazy pagination or server-side search: selected items may not be in the current page.

sortedValues

ComputedInFilterValueInfo[]

Distinct Column values sorted by the Column's own sort direction (Asc / Desc).

If the Column has no active sort, values are returned in the same order as defaultValues.

When the Column uses a Tree Filter, items have a hierarchical structure.

Computed lazily on first access.

adaptableContext

any

Custom application Context provided in AdaptableOptions.adaptableContext

InFilterValueResult

Result when providing custom values for the IN Column Filter

hasMore?

boolean

When true, scrolling near the end of the list re-invokes customInFilterValues
with a larger offset. New values are appended (same search).
Search changes reset the list and set offset back to 0.

inFilterLabel?

(context:InFilterLabelContext) => string

Custom text for the collapsed IN Filter input.

Receives an and must return a string.

When omitted, the input shows the selected count (e.g. (3)) followed by the
selected labels joined with a comma. When provided, it fully replaces that
text (including the count - render one yourself if you want it).

For tree-shaped filters (group columns and date columns), each selected leaf
is one entry in selectedValues: its value is the full leaf path and its
label the joined path label. selectedCount is the number of selected leaves.

skipDefaultSearch?

boolean

If true, AdapTable will not filter the list using the current search value

values

InFilterValue[]

List of Items to display in the IN Column Filter

isRowFilterable receives an IsRowFilterableContext:

Find Out More

See Configuring Filters for how these options are used

Filter State

There is no separate Filter section in Initial Adaptable State.

Column Filters and the Grid Filter are properties of a Layout, defined in Layout Initial State.

Column Filter

ColumnFilter

A filter on one column in a layout.

Expression is a boolean AdapTableQL expression and is what hides rows. PreferredFilter is only the operator shown in the filter UI before an expression exists; it does not hide rows. Setting Expression clears PreferredFilter. IsSuspended: true turns the filter off.

Extends

SuspendableObject

ColumnId

string

Column where Filter should be applied

Expression?

string

AdaptableQL boolean expression evaluated for each row, e.g.

[price] > 100 AND [price] < 200 OR [price] = 350

Mutually exclusive with : when
Expression is set, PreferredFilter is not persisted.

PreferredFilter?

string

Preferred filter operator when there is no Expression (UI seed only —
does not filter rows). Uses AQL operator / function names, the same
vocabulary as columnFilterOptions.default*ColumnFilter (e.g. 'IN',
'STARTS_WITH', 'EQ').

Mutually exclusive with : set when the
user selects an operator before the filter is complete; removed as
soon as a valid Expression is persisted; restored from the current
UI operator when the Expression is cleared.

IsReadOnly?

boolean

Sets Entity to ReadOnly (overwriting a Strategy Entitlement of 'Full')

IsSuspended?

boolean

Suspends (i.e. turns off) an Adaptable Object

Grid Filter

GridFilter

A boolean AdapTableQL expression applied to every row in a layout.

Rows that do not match Expression are hidden. An empty expression, or IsSuspended: true, shows every row. This is separate from each column's ColumnFilter.

Extends

SuspendableObject

Expression?

string

The (boolean) Expression to run

IsReadOnly?

boolean

Sets Entity to ReadOnly (overwriting a Strategy Entitlement of 'Full')

IsSuspended?

boolean

Suspends (i.e. turns off) an Adaptable Object

Filter API

FilterApi

Provides run-time access to Filtering in AdapTable

clearAllFilters()
returns

void

Clears all Filters in AdapTable - both Column and Grid

Column Filter API

ColumnFilterApi

Column Filters in the current Layout: read, set and clear them, and test whether a filter is active.

clearAndSetColumnFilters(columnFilters)
returns

void

Clears existing Column Filters and sets new ones

clearColumnFilter(columnFilter)
returns

void

Clears given Column Filter in the current Layout

clearColumnFilterForColumn(columnId)
returns

void

Clears Column Filter for given Column

clearColumnFilters()
returns

void

Clears all Column Filters in the Current Layout

clearColumnFiltersForColumns(columns)
returns

void

Clears Column Filters for given set of Columns

columnFiltersToString(columnFilters)
returns

string

Retrieves descriptions of given Column Filters

columnFilterToString(columnFilter)
returns

string

Retrieves description of given Column Filter

getActiveColumnFilters()
returns

ColumnFilter[]

Retrieves all active/no-suspended Column Filters in currently applied Layout

getColumnFilterForColumn(columnId)
returns

ColumnFilter | undefined

Retrieves the Column Filter for the specified Column.

getColumnFilters()
returns

ColumnFilter[]

Retrieves all Column Filters in currently applied Layout

getColumnFiltersForLayout(layoutName)
returns

ColumnFilter[]

Retrieves all Column Filters in a given Layout

hideColumnFilterMenu()
returns

void

Hides Column Filter Menu

hideQuickFilterBar()
returns

void

Hides Quick Filter bar

isColumnFilterActive(columnFilter)
returns

boolean

Whether a Column Filter is filtering rows. Active when it is not suspended and its expression is not empty.

isColumnFilterActiveForColumn(columnId)
returns

boolean

Whether the given column has an active Column Filter

isQuickFilterAvailable()
returns

boolean

Whether Quick Filter is available for use

isQuickFilterVisible()
returns

boolean

Whether Quick Filter Form is currently visible

refreshAllFilterValues()
returns

Promise<Record<string,InFilterValueResult>>

Refreshes (reloads) the filter values for ALL Columns (for IN Filter).

refreshFilterValues(columnId)
returns

Promise<InFilterValueResult>

Refresh(reload) the filter values for a given Column (for IN Filter).

resetAllFilterValues()
returns

void

Reset(clear cache) the filter values for ALL Columns (for IN Filter).

resetFilterValues(columnId)
returns

void

Reset(clear cache) the filter values for a given Column (for IN Filter).

setColumnFilters(columnFilters)
returns

ColumnFilter[] | null

Sets Column Filters in current Layout; replaces filters for existing column, leaving other column filters in place

showQuickFilterBar()
returns

void

Makes Quick Filter Bar appear

suspendAllColumnFilters()
returns

void

Suspends all Column Filters

suspendColumnFilter(columnFilter)
returns

void

Suspends a Column Filter

unSuspendAllColumnFilters()
returns

void

Unsuspend all Column Filters

unSuspendColumnFilter(columnFilter)
returns

void

Unsuspend a Column Filter

Grid Filter API

GridFilterApi

Provides run-time access to Grid Filter section of Adaptable State.

clearGridFilter()
returns

void

Clears the Grid Filter (for the current Layout)

getCurrentGridFilter()
returns

GridFilter | undefined

Retrieves the Grid Filter from the current Layout

getCurrentGridFilterExpression()
returns

string | undefined

Retrieves the Grid Filter's Expression from the current layout

openUIEditorForGridFilter(expression)
returns

void

Opens the Grid Filter Settings Panel (Expression Editor & Query Builder).

reApplyGridFilter()
returns

void

Re-applies the Grid Filter

setGridFilterExpression(expression)
returns

void

Sets the Grid Filter (for the current layout)

If expression is null, undefined or a blank string the Grid Filter
is cleared (equivalent to calling ). This makes
it safe to drive the Grid Filter from form-style controls that emit
empty values when the user deselects everything, without having to
branch in the caller.

setGridFilterExpressionUsingNamedQuery(namedQuery)
returns

void

Sets the Grid Filter (for the current layout)

suspendGridFilter()
returns

void

Suspends the Grid Filter

unSuspendGridFilter()
returns

void

Unsuspends the Grid Filter

Filter Events

Column Filter Changed Event

The Column Filter Changed Event fires for every Column Filter editor or state change — including incomplete drafts that are not persisted.

Prefer this Event for new code. Use isApplied to ignore drafts, and isComplete to tell a finished Expression from a clear or an incomplete editor.

Hint

This is often used when wanting to evaluate expressions on the Server

ColumnFilterChangedInfo

The Event's ColumnFilterChangedInfo object is defined as follows:

ColumnFilterChangedInfo

EventInfo returned by the ColumnFilterChanged event.

Fires for every column-filter editor or state change — including incomplete drafts (e.g. operator chosen, value not yet valid) that are not persisted.

Prefer this over ColumnFilterApplied when you need to observe in-progress edits. Use isApplied to ignore drafts.

Extends

BaseContext

columnFilters

ColumnFilter[]

Currently persisted Column Filters after this change.
Unchanged when isApplied is false.

columnId?

string

Column whose filter changed.
Undefined for bulk actions (e.g. clear/suspend all).

expression?

string

Expression for columnId after this change when available.
May be omitted for incomplete drafts with nothing persistable yet.

isApplied

boolean

True when persisted Column Filters were updated (layout state) and grid
filtering may change. False when only an in-progress editor draft changed
(incomplete expression, or manual-apply pending Apply).

When true, ColumnFilterApplied is also
emitted for backward compatibility.

isComplete

boolean

Whether the filter expression for this change is fully specified.

- When isApplied is false: the editor draft is valid (not e.g. an
operator with a missing value). False for incomplete drafts.
- When isApplied is true: a complete Expression was written or remains
for the column. False when the column filter was cleared/deactivated.

These flags diverge for clear/deactivate (isComplete: false,
isApplied: true), incomplete drafts (false/false), manual-apply
pending Apply (true/false), and the usual complete apply (true/true).

adaptableContext

any

Custom application Context provided in AdaptableOptions.adaptableContext

Event Subscription

Subscribing to the Event is done the same way as with all Adaptable Events:

api.eventApi.on('ColumnFilterChanged', (eventInfo: ColumnFilterChangedInfo) => {
  if (eventInfo.isApplied) {
    // persisted Filters changed — grid filtering may run
  }
});

Column Filter Applied Event

ColumnFilterApplied is still emitted whenever ColumnFilterChanged fires with isApplied: true.

Use ColumnFilterChanged for new subscriptions. Existing ColumnFilterApplied listeners keep working.

ColumnFilterAppliedInfo

The Event's ColumnFilterAppliedInfo object contains the currently applied Column Filters and an AST for each Filter Expression (columnFilterExpressionASTs, same order as columnFilters):

ColumnFilterAppliedInfo

EventInfo returned by the ColumnFilterApplied event.

Fired when persisted Column Filters change (layout state updated; grid filtering may run). Incomplete editor drafts do not fire this event.

For in-progress edits as well as applies, prefer ColumnFilterChanged and check isApplied. ColumnFilterApplied remains supported and is emitted alongside ColumnFilterChanged whenever isApplied is true.

Extends

BaseContext

columnFilterExpressionASTs

Array<any | null>

AST for each applied Column Filter Expression, index-aligned with
. null when that filter has no Expression or the
Expression is not currently parsable.

columnFilters

ColumnFilter[] | undefined

Currently applied Column Filters

adaptableContext

any

Custom application Context provided in AdaptableOptions.adaptableContext

Grid Filter Applied Event

The Grid Filter Applied Event is triggered whenever a Grid Filter is applied in AdapTable.

Find Out More

This is often used when wanting to manage expressions on the Server

GridFilterAppliedInfo

The Grid Filter Applied Event has a GridFilterAppliedInfo object defined as follows:

GridFilterAppliedInfo

Payload of the GridFilterApplied event.

Fires when the Grid Filter on the current Layout is set, cleared, suspended or unsuspended.

Extends , so adaptableApi is included.

Extends

BaseContext

gridFilter

GridFilter | undefined

Grid Filter on the current Layout after this change.

undefined when the Layout has no Grid Filter (including after it is cleared).

gridFilterExpressionAST

any

AST of gridFilter.Expression.

null when the Layout has no Grid Filter.

adaptableContext

any

Custom application Context provided in AdaptableOptions.adaptableContext

Event Subscription

Subscribing to the Event is done the same way as with all Adaptable Events:

api.eventApi.on('GridFilterApplied', (eventInfo: GridFilterAppliedInfo) => {
    // do something with the info
});

System Filter Operators

Column Filter operators are boolean Expression Functions (e.g. EQ, CONTAINS, IS_BLANK, IS_SAME_DAY).

Which operators appear for a Column depends on its Column Data Type.

See the System Filters appendix for the full list by Data Type.

Hint

  • Developers can add their own operators via Custom Column Filters (boolean Expression Functions)
  • They can also limit - or extend - which operators are available via System Filters
PreviousGuide to FilteringNextColumn Filters