Skip to content

Filters

See the Column filter guide for examples and configuration details.

Description

Initializes the plugin and registers the column header hook needed to inject the filter UI.

Options

filters

Can be set at: grid columns

Source code

filters.filters : boolean | object

The filters option configures the Filters plugin.

The option takes different values at the two levels it works at, so they are listed separately below. At the grid level it switches the plugin on and carries its settings. Inside columns, false takes that column out of filtering, and an object can set the column’s own availableConditions.

At the grid level:

SettingDescription
falseDisable the Filters plugin
trueEnable the Filters plugin
An objectEnable the Filters plugin with custom settings

If you set the filters option to an object, you can configure the following settings. searchMode and filterFixedRows are read once, for the whole grid, so they cannot be set per column. availableConditions can be set at both levels:

PropertyPossible valuesDefaultDescription
searchMode'show' | 'apply''show'Enable filtering only visible elements
filterFixedRowstrue | falsetruetrue: Filter the whole dataset, including the rows pinned by fixedRowsTop and fixedRowsBottom
false: Leave the pinned rows out of the filter
availableConditionsAn array | An objectundefinedThe operators the Filter by condition lists offer. See below.

availableConditions takes one of three shapes:

ShapeDescription
An array of condition namesOffer only these conditions, in this order. '---------' adds a separator.
{ exclude: [...] }Offer the default list for the column’s data type, minus these conditions.
An object keyed by data typeOne of the two shapes above per data type: text, numeric, date, intl-date, intl-time, intl-datetime.

The condition names are the ones addCondition() takes, for example 'eq', 'gt', 'between', or 'not_between'. A column whose type has no list of its own (for example dropdown) uses the text list. A checkbox column uses the text list with 'checked' and 'unchecked' added (unless a data provider backs the grid), and follows the text key of a per-type object. There is no checkbox key: to offer a checkbox column only 'empty', 'not_empty', 'checked', and 'unchecked', set availableConditions on that column. None always stays first. A name the column’s data type does not offer is left out. The setting changes the lists only: a condition added through addCondition() still filters, and its select still shows it.

When the grid is created, and when the setting changes, a console warning names each condition that no data type offers, each listed condition a column’s data type does not offer, and each data type key without a list of its own. Such a key is ignored; the other entries still apply.

A column’s own availableConditions replaces the grid-level one for that column. The two are not merged. A column whose own value is undefined uses the grid-level value.

Updating the filters option through updateSettings() clears the filters that are applied. A filters object that leaves out availableConditions keeps the previous value, and setting filters to false does not clear it either. Pass availableConditions: undefined or filters: true to go back to the default lists.

availableConditions changes what the condition lists contain, not which parts the menu shows. The dropdownMenu option decides that, so if its configuration leaves out or hides filter_by_condition, the setting has nothing to act on.

Set filterFixedRows to false when the pinned rows hold totals or headings rather than data. Those rows are then never hidden by a filter, and their values are not offered in the Filter by value list.

filterFixedRows has no effect while the DataProvider plugin is active: filtering then happens on the server, which knows nothing about frozen rows.

With filterFixedRows: false and a filter applied, the grid works out again which rows are exempt when the rows change, on the next render. Inserting or removing a row (including through updateData()) always does it. Moving a row, sorting, or changing fixedRowsTop or fixedRowsBottom does it only when a different row ends up frozen, so a sort that keeps the frozen rows in place (the columnSorting default) costs nothing. This is not a new filter: the conditions stay the same, the beforeFilter and afterFilter hooks do not fire, the selection does not move, and no undo step is recorded. Inside a batch(), data read before the batch ends still reflects the previous frozen rows.

Inside columns:

SettingDescription
falseHide the filter controls in this column’s dropdown menu
{ availableConditions: ... }Choose the operators this column’s Filter by condition lists offer
Anything elseNo effect – the column keeps whatever the grid-level setting gave it

The column’s dropdown menu still opens, so entries such as Clear column stay available. The plugin’s API is not affected either: addCondition() still filters such a column, the same way columnSorting’s headerAction leaves sorting through the API working.

Inside columns, an object is read for availableConditions only. Any other key in it, such as searchMode or filterFixedRows, is ignored, and logs a warning once per grid. Since 19.0, TypeScript rejects it too: a column’s filters is typed boolean or { availableConditions }, and the grid-level object accepts only searchMode, filterFixedRows, and availableConditions.

The switch is read from the column meta, which the cells and cell options do not reach, so filtering cannot be turned off for a single cell. Filtering works on whole columns, so there would be nothing for a per-cell value to mean.

Read more:

Default: undefined
Example

// enable the `Filters` plugin
filters: true,
// enable it, and keep the frozen rows out of the filter
filters: {
filterFixedRows: false,
},
// turn filtering off for the second column only
filters: true,
columns: [
{},
{ filters: false },
],
// remove "Is not between" from every numeric column
filters: {
availableConditions: {
numeric: { exclude: ['not_between'] },
},
},
// offer only a few operators in one column, in this order
filters: true,
columns: [
{ filters: { availableConditions: ['eq', 'neq', '---------', 'empty', 'not_empty'] } },
{},
],
// WRONG: `filterFixedRows` is grid-level, so it is ignored here, warns, and does not compile
columns: [
{ filters: { filterFixedRows: false } },
],

filterValueComparator

Can be set at: grid columns

Source code

filters.filterValueComparator : function

The filterValueComparator option sets the order of the values in the Filter by value list of the Filters dropdown.

By default the list places blank cells first and then sorts the values with a built-in comparator: numbers by value, text by character code, and date, intl-date, and intl-datetime cells chronologically. Set filterValueComparator to a function to replace that order. The function takes two cell values and returns a negative number, zero, or a positive number, like the callback of Array.prototype.sort().

The option cascades: set it at the grid level to order every column’s list the same way, or inside columns to order one column. A column value overrides the grid value. A custom comparator also overrides the cell type’s own comparator.

Two details to know when you write the function:

  • A blank cell (null, undefined, or '') reaches the comparator as an empty string ''.
  • The comparator only orders the list. It cannot add, hide, or remove a value, so it never changes which rows the filter keeps.

A value that is not a function is ignored, and the built-in order applies.

The list is built once per column, and the comparator is read from the cell meta of the first row the list is built from. A per-cell value set through cells or cell is therefore not a reliable way to configure it. Set it at the grid level or inside columns.

Read more:

Default: undefined
Since: 19.0.0
Example

// order the "Priority" column by severity rather than alphabetically
const priority = ['Critical', 'High', 'Medium', 'Low'];
filters: true,
columns: [
{
data: 'priority',
filterValueComparator: (a, b) => priority.indexOf(a) - priority.indexOf(b),
},
],
// order every column's list with a locale-aware text comparison
filters: true,
filterValueComparator: (a, b) => String(a).localeCompare(String(b), 'de'),

Members

DEFAULT_SETTINGS

Source code

Filters.DEFAULT_SETTINGS

Returns the default settings applied when the plugin is enabled without explicit configuration.

LICENSE

Source code

Filters.LICENSE

Returns the license token of the plugin, its display name, where it is checked, and the tokens it requires.

PLUGIN_DEPS

Source code

Filters.PLUGIN_DEPS

Returns the list of plugin dependencies required before this plugin can be initialized.

PLUGIN_KEY

Source code

Filters.PLUGIN_KEY

Returns the plugin key used to identify this plugin in Handsontable settings.

PLUGIN_PRIORITY

Source code

Filters.PLUGIN_PRIORITY

Returns the priority order used to determine the order in which plugins are initialized.

SETTINGS_VALIDATORS

Source code

Filters.SETTINGS_VALIDATORS

Returns validator functions for each plugin setting to verify their values are valid before applying them.

Methods

addCondition

Source code

filters.addCondition(column, name, args, [operationId])

Adds condition to the conditions collection at specified column index.

Possible predefined conditions:

ConditionDescriptionExpected args
begins_withBegins with[value: string], e.g. ['de']
betweenBetween[from: number|string, to: number|string], e.g. [10, 50]
by_valueBy value[[...values: Array]], e.g. [['ing', 'ed', 'as']]. The outer array wraps a single inner array that contains all values to keep (show) after filtering.
checkedIs checked, for a checkbox column: the value matches the cell’s checkedTemplate (true by default), ignoring letter case. With a dataProvider, your server must handle this name[]
containsContains[value: string], e.g. ['ing']
date_afterAfter a date (exclusive)[dateString: string], e.g. ['1/1/2023']. The format must match the column’s dateFormat option.
date_after_or_equalAfter or equal to a date (inclusive)[dateString: string], e.g. ['1/1/2023']. The format must match the column’s dateFormat option.
date_beforeBefore a date (exclusive)[dateString: string], e.g. ['1/1/2023']. The format must match the column’s dateFormat option.
date_before_or_equalBefore or equal to a date (inclusive)[dateString: string], e.g. ['1/1/2023']. The format must match the column’s dateFormat option.
date_todayToday[]
date_tomorrowTomorrow[]
date_yesterdayYesterday[]
emptyEmpty[]
ends_withEnds with[value: string], e.g. ['ing']
eqEqual[value: string|number], e.g. ['John']. On date and intl-date columns, pass an ISO 8601 date string, e.g. ['2023-01-01'].
gtGreater than[value: number], e.g. [95]
gteGreater than or equal[value: number], e.g. [95]
intl_date_afterAfter a date, exclusive (locale-aware)[dateString: string], e.g. ['2023-01-01']
intl_date_after_or_equalAfter or equal to a date, inclusive (locale-aware)[dateString: string], e.g. ['2023-01-01']
intl_date_beforeBefore a date, exclusive (locale-aware)[dateString: string], e.g. ['2023-01-01']
intl_date_before_or_equalBefore or equal to a date, inclusive (locale-aware)[dateString: string], e.g. ['2023-01-01']
intl_date_betweenBetween dates (locale-aware)[fromDateString: string, toDateString: string], e.g. ['2023-01-01', '2023-12-31']
intl_date_todayToday (locale-aware)[]
intl_date_tomorrowTomorrow (locale-aware)[]
intl_date_yesterdayYesterday (locale-aware)[]
intl_time_afterAfter a time (locale-aware)[timeString: string], e.g. ['12:00']
intl_time_beforeBefore a time (locale-aware)[timeString: string], e.g. ['08:00']
intl_time_betweenBetween times (locale-aware)[fromTimeString: string, toTimeString: string], e.g. ['08:00', '12:00']
ltLess than[value: number], e.g. [10]
lteLess than or equal[value: number], e.g. [10]
noneNone (no filter)[]. Matches every row, so it has no filtering effect. To clear a column’s filter, use removeConditions() instead.
not_betweenNot between[from: number|string, to: number|string], e.g. [10, 50]
not_containsNot contains[value: string], e.g. ['ing']
not_emptyNot empty[]
neqNot equal[value: string|number], e.g. ['John']. On date and intl-date columns, pass an ISO 8601 date string, e.g. ['2023-01-01'].
uncheckedIs unchecked, for a checkbox column: the value matches the cell’s uncheckedTemplate (false by default), ignoring letter case. An empty cell does not match unless the template is itself empty; use empty for it. With a dataProvider, your server must handle this name[]

Possible operations on collection of conditions:

  • conjunction - Conjunction on conditions collection (by default), i.e. for such operation:
    c1 AND c2 AND c3 AND c4 … AND cn === TRUE, where c1 … cn are conditions.
  • disjunction - Disjunction on conditions collection, i.e. for such operation:
    c1 OR c2 OR c3 OR c4 … OR cn === TRUE, where c1, c2, c3, c4 … cn are conditions.
  • disjunctionWithExtraCondition - Disjunction on first n - 1* conditions from collection with an extra requirement computed from the last condition, i.e. for such operation:
    c1 OR c2 OR c3 OR c4 … OR cn-1 AND cn === TRUE, where c1, c2, c3, c4 … cn are conditions.

* when n is collection size; it’s used i.e. for one operation introduced from UI (when choosing from filter’s drop-down menu two conditions with OR operator between them, mixed with choosing values from the multiple choice select)

Note: Mind that you cannot mix different types of operations (for instance, if you use conjunction, use it consequently for a particular column).

Note: If the number of conditions added programmatically via addCondition() exceeds the capacity of the filter’s dropdown UI (at most 2 regular conditions and 1 by_value condition per column), the extra conditions will be applied to the data but will not be visible or editable in the dropdown menu.

Example

import { AfterViewInit, Component, ViewChild } from "@angular/core";
import {
GridSettings,
HotTableModule,
HotTableComponent,
} from "@handsontable/angular-wrapper";
`@Component`({
selector: "app-example",
standalone: true,
imports: [HotTableModule],
template: ` <div>
<hot-table [settings]="gridSettings" />
</div>`,
})
export class ExampleComponent implements AfterViewInit {
`@ViewChild`(HotTableComponent, { static: false })
readonly hotTable!: HotTableComponent;
readonly gridSettings = <GridSettings>{
data: this.getData(),
filters: true,
};
ngAfterViewInit(): void {
// Access to filters plugin instance
const hot = this.hotTable.hotInstance;
const filtersPlugin = hot.getPlugin("filters");
// Add filter "Begins with" with value "de" to column at index 1
filtersPlugin.addCondition(1, "begins_with", ["de"]);
filtersPlugin.filter();
// Add filter "Between" 10 and 50 to column at index 1
filtersPlugin.addCondition(1, "between", [10, 50]);
filtersPlugin.filter();
// Add filter "By value" to column at index 1
// In this case, all values that don't match will be filtered.
filtersPlugin.addCondition(1, "by_value", [["ing", "ed", "as", "on"]]);
filtersPlugin.filter();
// Add filter "Contains" with value "ing" to column at index 1
filtersPlugin.addCondition(1, "contains", ["ing"]);
filtersPlugin.filter();
// Add filter "After a date" with value "1/1/2023" to column at index 1
filtersPlugin.addCondition(1, "date_after", ["1/1/2023"]);
filtersPlugin.filter();
// Add filter "Before a date" with value "1/1/2023" to column at index 1
filtersPlugin.addCondition(1, "date_before", ["1/1/2023"]);
filtersPlugin.filter();
// Add filter "Today" with no arguments to column at index 1
filtersPlugin.addCondition(1, "date_today", []);
filtersPlugin.filter();
// Add filter "Tomorrow" with no arguments to column at index 1
filtersPlugin.addCondition(1, "date_tomorrow", []);
filtersPlugin.filter();
// Add filter "Yesterday" with no arguments to column at index 1
filtersPlugin.addCondition(1, "date_yesterday", []);
filtersPlugin.filter();
// Add filter "Empty" with no arguments to column at index 1
filtersPlugin.addCondition(1, "empty", []);
filtersPlugin.filter();
// Add filter "Ends with" with value "ing" to column at index 1
filtersPlugin.addCondition(1, "ends_with", ["ing"]);
filtersPlugin.filter();
// Add filter "Equal" with value "John" to column at index 1
filtersPlugin.addCondition(1, "eq", ["John"]);
filtersPlugin.filter();
// Add filter "Greater than" 95 to column at index 1
filtersPlugin.addCondition(1, "gt", [95]);
filtersPlugin.filter();
// Add filter "Greater than or equal" 95 to column at index 1
filtersPlugin.addCondition(1, "gte", [95]);
filtersPlugin.filter();
// Add filter "Less than" 10 to column at index 1
filtersPlugin.addCondition(1, "lt", [10]);
filtersPlugin.filter();
// Add filter "Less than or equal" 10 to column at index 1
filtersPlugin.addCondition(1, "lte", [10]);
filtersPlugin.filter();
// Add filter "None" with no arguments to column at index 1
filtersPlugin.addCondition(1, "none", []);
filtersPlugin.filter();
// Add filter "Not between" 10 and 50 to column at index 1
filtersPlugin.addCondition(1, "not_between", [10, 50]);
filtersPlugin.filter();
// Add filter "Not contains" with value "ing" to column at index 1
filtersPlugin.addCondition(1, "not_contains", ["ing"]);
filtersPlugin.filter();
// Add filter "Not empty" with no arguments to column at index 1
filtersPlugin.addCondition(1, "not_empty", []);
filtersPlugin.filter();
// Add filter "Not equal" with value "John" to column at index 1
filtersPlugin.addCondition(1, "neq", ["John"]);
filtersPlugin.filter();
}
private getData(): Array<*> {
// Get some data
}
}
ParamTypeDefaultDescription
columnnumberVisual column index.
namestringCondition short name.
argsArrayCondition arguments. The expected format depends on the condition - see the table above for details.
[operationId]string”conjunction”optional id of operation which is performed on the column.

clearConditions

Source code

filters.clearConditions([column])

Clears all conditions previously added to the collection for the specified column index or, if the column index was not passed, clear the conditions for all columns.

ParamTypeDescription
[column]numberoptional Visual column index.

destroy

Source code

filters.destroy()

Destroys the plugin instance.

disablePlugin

Source code

filters.disablePlugin()

Disables the plugin functionality for this Handsontable instance.

enablePlugin

Source code

filters.enablePlugin()

Enables the plugin functionality for this Handsontable instance.

exportConditions

Source code

filters.exportConditions() ⇒ Array

Exports filter conditions for all columns from the plugin. The array represents the filter state for each column and uses physical column indexes in each column property. For example:

[
{
column: 1,
operation: 'conjunction',
conditions: [
{ name: 'gt', args: [95] },
]
},
{
column: 7,
operation: 'conjunction',
conditions: [
{ name: 'contains', args: ['mike'] },
{ name: 'begins_with', args: ['m'] },
]
},
]

filter

Source code

filters.filter()

Filters data based on added filter conditions.

Emits: Hooks#event:beforeFilter, Hooks#event:afterFilter

getAvailableConditions

Source code

filters.getAvailableConditions(column) ⇒ Array<{name: string, inputsCount: number}>

Gets the filter conditions that a column offers, in the order the “Filter by condition” menu lists them.

The list follows the column’s data type (text, numeric, date, intl-date, intl-time, or intl-datetime, where any other type and a column whose cells have different types use the text list; a checkbox column adds checked and unchecked to it, unless a data provider backs the grid) and the availableConditions setting that applies to the column. It is the list the column’s menu shows, without the separators and without the “None” entry, which clears a filter rather than adding one. Like the menu, it reads the data type from the rows no filter trims, so in a column whose cells have different types the answer can change when a filter hides rows. A column with filters: false still gets its list, because that setting hides the menu but not the filter.

Use it to build valid conditions for Filters#addCondition, for example in a custom filter form. The entries that Filters#importConditions takes name physical columns, so convert the index with Core#toPhysicalColumn there. The “Filter by value” condition (by_value) is not in the list, because it is not a menu entry.

Since: 19.0.0
Example

const filtersPlugin = hot.getPlugin('filters');
filtersPlugin.getAvailableConditions(1);
// [
// { name: 'empty', inputsCount: 0 },
// { name: 'not_empty', inputsCount: 0 },
// { name: 'eq', inputsCount: 1 },
// ...
// { name: 'between', inputsCount: 2 },
// ]
ParamTypeDescription
columnnumberVisual column index.

Returns: Array<{name: string, inputsCount: number}> - The conditions, each with its name and the number of arguments it takes.

getDataMapAtColumn

Source code

filters.getDataMapAtColumn(physicalColumn, [physicalRows]) ⇒ Array<{row: number, meta: CellProperties, value: *}>

Returns the full dataset for a column with cell meta for each row. The dataset is independent of any index mapper - no matter if the data is filtered, sorted, or otherwise transformed all rows are included, unless physicalRows narrows the read to specific rows, or filterFixedRows is false, which drops the rows pinned by fixedRowsTop and fixedRowsBottom from the full read.

That single exclusion is what keeps pinned rows out of every consumer at once: DataFilter, the ConditionUpdateObserver memo, and the has-conditions branch of _getValueListDataAtColumn() all read the column through the same read as this method. A caller that passes physicalRows has already chosen its rows and is left alone.

ParamTypeDescription
physicalColumnnumberThe physical column index.
[physicalRows]Array<number>optional When provided, only these physical rows are read (in the given order) instead of every source row.

Returns: Array<{row: number, meta: CellProperties, value: *}> - Array of objects with row (the physical row index), meta, and value, one per read row. Consumers correlate rows through the row property - the coordinate stamps on meta are shared with other readers and may change after this method returns.

getSelectedColumn

Source code

filters.getSelectedColumn() ⇒ Object | null

Gets the last selected column as an object with visual and physical indexes.

Returns: Object | null - Returns null when a column is not selected. Otherwise, returns an object with visualIndex and physicalIndex properties containing column indexes.

importConditions

Source code

filters.importConditions(conditions)

Imports filter conditions to all columns to the plugin. The method accepts the array of conditions with the same structure as the Filters#exportConditions method returns. The column property in each condition object must be a physical column index. Importing conditions will replace the current conditions. Once replaced, the state of the condition will be reflected in the UI. To apply the changes and filter the table, call the Filters#filter method eventually.

ParamTypeDescription
conditionsArrayArray of conditions keyed by physical column indexes.

isEnabled

Source code

filters.isEnabled() ⇒ boolean

Checks if the plugin is enabled in the handsontable settings. This method is executed in Hooks#beforeInit hook and if it returns true then the Filters#enablePlugin method is called.

removeConditions

Source code

filters.removeConditions(column)

Removes conditions at specified column index.

This is the programmatic equivalent of selecting the None operator in the column menu – both clear the column’s filter.

ParamTypeDescription
columnnumberVisual column index.

updatePlugin

Source code

filters.updatePlugin()

Update plugin state after Handsontable settings update.