Filters

Description

The plugin allows filtering the table data either by the built-in component or with the API.

Example

1
settings = {
2
  data: getData(),
3
  colHeaders: true,
4
  rowHeaders: true,
5
  dropdownMenu: true,
6
  filters: true,
7
};

1
<hot-table [settings]="settings"></hot-table>

Options

filters

Source code

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.

Default: undefined
Example

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

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)	`[]`
`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

1
import { AfterViewInit, Component, ViewChild } from "@angular/core";
2
import {
3
  GridSettings,
4
  HotTableModule,
5
  HotTableComponent,
6
} from "@handsontable/angular-wrapper";
7

8
`@Component`({
9
  selector: "app-example",
10
  standalone: true,
11
  imports: [HotTableModule],
12
  template: ` <div>
13
    <hot-table [settings]="gridSettings" />
14
  </div>`,
15
})
16
export class ExampleComponent implements AfterViewInit {
17
  `@ViewChild`(HotTableComponent, { static: false })
18
  readonly hotTable!: HotTableComponent;
19

20
  readonly gridSettings = <GridSettings>{
21
    data: this.getData(),
22
    filters: true,
23
  };
24

25
  ngAfterViewInit(): void {
26
    // Access to filters plugin instance
27
    const hot = this.hotTable.hotInstance;
28
    const filtersPlugin = hot.getPlugin("filters");
29

30
    // Add filter "Begins with" with value "de" to column at index 1
31
    filtersPlugin.addCondition(1, "begins_with", ["de"]);
32
    filtersPlugin.filter();
33

34
    // Add filter "Between" 10 and 50 to column at index 1
35
    filtersPlugin.addCondition(1, "between", [10, 50]);
36
    filtersPlugin.filter();
37

38
    // Add filter "By value" to column at index 1
39
    // In this case, all values that don't match will be filtered.
40
    filtersPlugin.addCondition(1, "by_value", [["ing", "ed", "as", "on"]]);
41
    filtersPlugin.filter();
42

43
    // Add filter "Contains" with value "ing" to column at index 1
44
    filtersPlugin.addCondition(1, "contains", ["ing"]);
45
    filtersPlugin.filter();
46

47
    // Add filter "After a date" with value "1/1/2023" to column at index 1
48
    filtersPlugin.addCondition(1, "date_after", ["1/1/2023"]);
49
    filtersPlugin.filter();
50

51
    // Add filter "Before a date" with value "1/1/2023" to column at index 1
52
    filtersPlugin.addCondition(1, "date_before", ["1/1/2023"]);
53
    filtersPlugin.filter();
54

55
    // Add filter "Today" with no arguments to column at index 1
56
    filtersPlugin.addCondition(1, "date_today", []);
57
    filtersPlugin.filter();
58

59
    // Add filter "Tomorrow" with no arguments to column at index 1
60
    filtersPlugin.addCondition(1, "date_tomorrow", []);
61
    filtersPlugin.filter();
62

63
    // Add filter "Yesterday" with no arguments to column at index 1
64
    filtersPlugin.addCondition(1, "date_yesterday", []);
65
    filtersPlugin.filter();
66

67
    // Add filter "Empty" with no arguments to column at index 1
68
    filtersPlugin.addCondition(1, "empty", []);
69
    filtersPlugin.filter();
70

71
    // Add filter "Ends with" with value "ing" to column at index 1
72
    filtersPlugin.addCondition(1, "ends_with", ["ing"]);
73
    filtersPlugin.filter();
74

75
    // Add filter "Equal" with value "John" to column at index 1
76
    filtersPlugin.addCondition(1, "eq", ["John"]);
77
    filtersPlugin.filter();
78

79
    // Add filter "Greater than" 95 to column at index 1
80
    filtersPlugin.addCondition(1, "gt", [95]);
81
    filtersPlugin.filter();
82

83
    // Add filter "Greater than or equal" 95 to column at index 1
84
    filtersPlugin.addCondition(1, "gte", [95]);
85
    filtersPlugin.filter();
86

87
    // Add filter "Less than" 10 to column at index 1
88
    filtersPlugin.addCondition(1, "lt", [10]);
89
    filtersPlugin.filter();
90

91
    // Add filter "Less than or equal" 10 to column at index 1
92
    filtersPlugin.addCondition(1, "lte", [10]);
93
    filtersPlugin.filter();
94

95
    // Add filter "None" with no arguments to column at index 1
96
    filtersPlugin.addCondition(1, "none", []);
97
    filtersPlugin.filter();
98

99
    // Add filter "Not between" 10 and 50 to column at index 1
100
    filtersPlugin.addCondition(1, "not_between", [10, 50]);
101
    filtersPlugin.filter();
102

103
    // Add filter "Not contains" with value "ing" to column at index 1
104
    filtersPlugin.addCondition(1, "not_contains", ["ing"]);
105
    filtersPlugin.filter();
106

107
    // Add filter "Not empty" with no arguments to column at index 1
108
    filtersPlugin.addCondition(1, "not_empty", []);
109
    filtersPlugin.filter();
110

111
    // Add filter "Not equal" with value "John" to column at index 1
112
    filtersPlugin.addCondition(1, "neq", ["John"]);
113
    filtersPlugin.filter();
114
  }
115

116
  private getData(): any[] {
117
    // Get some data
118
  }
119
}

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. 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) ⇒ Array<{meta: CellProperties, value: any}>

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.

Param	Type	Description
physicalColumn	`number`	The physical column index.

Returns: Array<{meta: CellProperties, value: any}> - Array of objects with meta and value, one per source row.

getSelectedColumn

Source code

filters.getSelectedColumn() ⇒ Object | null

Gets last selected column index.

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

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. 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.

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.

Param	Type	Description
column	`number`	Visual column index.

updatePlugin

Source code

filters.updatePlugin()

Update plugin state after Handsontable settings update.