Filters

Description

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

Options

filters

Can be set at: grid columns

Ask AI

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 it does one thing only: false takes that column out of filtering.

At the grid level:

Setting	Description
false	Disable the Filters plugin
true	Enable the Filters plugin
An object	Enable the Filters plugin with custom settings

If you set the filters option to an object, you can configure the following settings. Both of them are read once, for the whole grid, so neither can be set per column:

Property	Possible values	Default	Description
searchMode	'show' | 'apply'	'show'	Enable filtering only visible elements
filterFixedRows	true | false	true	true: Filter the whole dataset, including the rows pinned by fixedRowsTop and fixedRowsBottom false: Leave the pinned rows out of the filter

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, changing the row order re-runs the filter. Inserting, removing, or moving a row, and sorting, all change which rows sit in the frozen panes, so the exemption has to be worked out again. The beforeFilter and afterFilter hooks fire on those changes as well. Read them as “the filter ran”, not as “the user changed a filter”.

Inside columns:

Setting	Description
false	Hide the filter controls in this column’s dropdown menu
Anything else	No 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.

An object written inside columns is ignored, and logs a warning once per grid. TypeScript does not reject it, because a column’s settings are typed from the grid’s, so treat the table above as the contract rather than the type.

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:

• Column filter
• dropdownMenu
• filterValueComparator – order the values in the Filter by value list

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 },
],

// WRONG: the sub-options are grid-level, so this object is ignored and warns
columns: [
  { filters: { filterFixedRows: false } },
],

filterValueComparator

Can be set at: grid columns

Ask AI

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:

• Column filter: Change the order of values in the filter list
• filters

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

Ask AI

Source code

Filters.DEFAULT_SETTINGS

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

PLUGIN_DEPS

Ask AI

Source code

Filters.PLUGIN_DEPS

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

PLUGIN_KEY

Ask AI

Source code

Filters.PLUGIN_KEY

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

PLUGIN_PRIORITY

Ask AI

Source code

Filters.PLUGIN_PRIORITY

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

SETTINGS_VALIDATORS

Ask AI

Source code

Filters.SETTINGS_VALIDATORS

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

Methods

addCondition

Ask AI

Source code

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

Adds condition to the conditions collection at specified column index.

Possible predefined conditions:

Condition	Description	Expected args
begins_with	Begins with	[value: string], e.g. ['de']
between	Between	[from: number|string, to: number|string], e.g. [10, 50]
by_value	By 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.
contains	Contains	[value: string], e.g. ['ing']
date_after	After a date (exclusive)	[dateString: string], e.g. ['1/1/2023']. The format must match the column’s dateFormat option.
date_after_or_equal	After or equal to a date (inclusive)	[dateString: string], e.g. ['1/1/2023']. The format must match the column’s dateFormat option.
date_before	Before a date (exclusive)	[dateString: string], e.g. ['1/1/2023']. The format must match the column’s dateFormat option.
date_before_or_equal	Before or equal to a date (inclusive)	[dateString: string], e.g. ['1/1/2023']. The format must match the column’s dateFormat option.
date_today	Today	[]
date_tomorrow	Tomorrow	[]
date_yesterday	Yesterday	[]
empty	Empty	[]
ends_with	Ends with	[value: string], e.g. ['ing']
eq	Equal	[value: string|number], e.g. ['John']
gt	Greater than	[value: number], e.g. [95]
gte	Greater than or equal	[value: number], e.g. [95]
intl_date_after	After a date, exclusive (locale-aware)	[dateString: string], e.g. ['2023-01-01']
intl_date_after_or_equal	After or equal to a date, inclusive (locale-aware)	[dateString: string], e.g. ['2023-01-01']
intl_date_before	Before a date, exclusive (locale-aware)	[dateString: string], e.g. ['2023-01-01']
intl_date_before_or_equal	Before or equal to a date, inclusive (locale-aware)	[dateString: string], e.g. ['2023-01-01']
intl_date_between	Between dates (locale-aware)	[fromDateString: string, toDateString: string], e.g. ['2023-01-01', '2023-12-31']
intl_date_today	Today (locale-aware)	[]
intl_date_tomorrow	Tomorrow (locale-aware)	[]
intl_date_yesterday	Yesterday (locale-aware)	[]
intl_time_after	After a time (locale-aware)	[timeString: string], e.g. ['12:00']
intl_time_before	Before a time (locale-aware)	[timeString: string], e.g. ['08:00']
intl_time_between	Between times (locale-aware)	[fromTimeString: string, toTimeString: string], e.g. ['08:00', '12:00']
lt	Less than	[value: number], e.g. [10]
lte	Less than or equal	[value: number], e.g. [10]
none	None (no filter)	[]. Matches every row, so it has no filtering effect. To clear a column’s filter, use removeConditions() instead.
not_between	Not between	[from: number|string, to: number|string], e.g. [10, 50]
not_contains	Not contains	[value: string], e.g. ['ing']
not_empty	Not empty	[]
neq	Not equal	[value: string|number], e.g. ['John']

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

Param	Type	Default	Description
column	number		Visual column index.
name	string		Condition short name.
args	Array		Condition 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

Ask AI

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.

Param	Type	Description
[column]	number	optional Visual column index.

destroy

Ask AI

Source code

filters.destroy()

Destroys the plugin instance.

disablePlugin

Ask AI

Source code

filters.disablePlugin()

Disables the plugin functionality for this Handsontable instance.

enablePlugin

Ask AI

Source code

filters.enablePlugin()

Enables the plugin functionality for this Handsontable instance.

exportConditions

Ask AI

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

Ask AI

Source code

filters.filter()

Filters data based on added filter conditions.

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

getDataMapAtColumn

Ask AI

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 here. A caller that passes physicalRows has already chosen its rows and is left alone.

Param	Type	Description
physicalColumn	number	The 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

Ask AI

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

Ask AI

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.

Param	Type	Description
conditions	Array	Array of conditions keyed by physical column indexes.

isEnabled

Ask AI

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

Ask AI

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.

Param	Type	Description
column	number	Visual column index.

updatePlugin

Ask AI

Source code

filters.updatePlugin()

Update plugin state after Handsontable settings update.