Filters

Description

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

Options

filters

filters.filters : boolean

The filters option configures the Filters plugin.

You can set the filters option to one of the following:

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:

Property	Possible values	Description
`searchMode`	`'show'` \| `'apply'`	Enable filtering only visible elements

If filers is set to true, the searchMode option is set to 'show' by default.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Example

1
// enable the `Filters` plugin
2
filters: true,

Members

DEFAULT_SETTINGS

Source code

Filters.DEFAULT_SETTINGS

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

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:

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

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

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:

1
[
2
  {
3
    column: 1,
4
    operation: 'conjunction',
5
    conditions: [
6
      { name: 'gt', args: [95] },
7
    ]
8
  },
9
  {
10
    column: 7,
11
    operation: 'conjunction',
12
    conditions: [
13
      { name: 'contains', args: ['mike'] },
14
      { name: 'begins_with', args: ['m'] },
15
    ]
16
  },
17
]

filter

Source code

filters.filter()

Filters data based on added filter conditions.

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

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.

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

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.

Param	Type	Description
conditions	`Array`	Array 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.

Param	Type	Description
column	`number`	Visual column index.

updatePlugin

Source code

filters.updatePlugin()

Update plugin state after Handsontable settings update.