This page covers a next version of Handsontable, and is not published yet.

This page covers a non-latest version of Handsontable.

# Filters

# Description

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

See the filtering demo for examples.

Example

const container = document.getElementById('example');
const hot = new Handsontable(container, {
  data: getData(),
  colHeaders: true,
  rowHeaders: true,
  dropdownMenu: true,
  filters: true
});

# Options

# filters

Source code (opens new window)

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

Read more:

Default: undefined Example

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

# Methods

# addCondition

Source code (opens new window)

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

Adds condition to the conditions collection at specified column index.

Possible predefined conditions:

  • begins_with - Begins with
  • between - Between
  • by_value - By value
  • contains - Contains
  • empty - Empty
  • ends_with - Ends with
  • eq - Equal
  • gt - Greater than
  • gte - Greater than or equal
  • lt - Less than
  • lte - Less than or equal
  • none - None (no filter)
  • not_between - Not between
  • not_contains - Not contains
  • not_empty - Not empty
  • neq - Not equal.

Possible operations on collection of conditions:

  • conjunction - Conjunction (opens new window) 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 (opens new window) 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).

Example

const container = document.getElementById('example');
const hot = new Handsontable(container, {
  data: getData(),
  filters: true
});

// access to filters plugin instance
const filtersPlugin = hot.getPlugin('filters');

// add filter "Greater than" 95 to column at index 1
filtersPlugin.addCondition(1, 'gt', [95]);
filtersPlugin.filter();

// add filter "By value" to column at index 1
// in this case all value's that don't match will be filtered.
filtersPlugin.addCondition(1, 'by_value', [['ing', 'ed', 'as', 'on']]);
filtersPlugin.filter();

// add filter "Begins with" with value "de" AND "Not contains" with value "ing"
filtersPlugin.addCondition(1, 'begins_with', ['de'], 'conjunction');
filtersPlugin.addCondition(1, 'not_contains', ['ing'], 'conjunction');
filtersPlugin.filter();

// add filter "Begins with" with value "de" OR "Not contains" with value "ing"
filtersPlugin.addCondition(1, 'begins_with', ['de'], 'disjunction');
filtersPlugin.addCondition(1, 'not_contains', ['ing'], 'disjunction');
filtersPlugin.filter();
Param Type Default Description
column number Visual column index.
name string Condition short name.
args Array Condition arguments.
[operationId] string "conjunction" optional id of operation which is performed on the column.

# clearConditions

Source code (opens new window)

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 (opens new window)

filters.destroy()

Destroys the plugin instance.

# disablePlugin

Source code (opens new window)

filters.disablePlugin()

Disables the plugin functionality for this Handsontable instance.

# enablePlugin

Source code (opens new window)

filters.enablePlugin()

Enables the plugin functionality for this Handsontable instance.

# filter

Source code (opens new window)

filters.filter()

Filters data based on added filter conditions.

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

# getDataMapAtColumn

Source code (opens new window)

filters.getDataMapAtColumn([column]) ⇒ Array

Returns handsontable source data with cell meta based on current selection.

Param Type Description
[column] number optional The physical column index. By default column index accept the value of the selected column.

Returns: Array - Returns array of objects where keys as row index.

# getSelectedColumn

Source code (opens new window)

filters.getSelectedColumn() ⇒ object | null

Gets last selected column index.

Returns: object | null - Return null when column isn't selected otherwise object containing information about selected column with keys visualIndex and physicalIndex.

# isEnabled

Source code (opens new window)

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 than the Filters#enablePlugin method is called.

# removeConditions

Source code (opens new window)

filters.removeConditions(column)

Removes conditions at specified column index.

Param Type Description
column number Visual column index.
Last Updated: Apr 19, 2024