Filtering

You can filter data on the client side by one or several criteria using built-in or custom filters.

Built-in Filters

You can define a built-in filter in the header or footer of a column. Webix DataGrid offers various filter types:

in a standard free version:
- textFilter
- serverFilter (based on the textFilter)
- selectFilter
- serverSelectFilter (based on the selectFilter)
- numberFilter
- dateFilter
additionally, in the Webix DataGrid Pro edition:
- richSelectFilter
- serverRichSelectFilter (based on the richSelectFilter)
- multiSelectFilter
- serverMultiSelectFilter (based on the multiSelectFilter)
- multiComboFilter
- serverMultiComboFilter (based on the multiComboFilter)
- datepickerFilter
- dateRangeFilter
- serverDateRangeFilter (based on the dateRangeFilter)
- excelFilter
- serverExcelFilter (based on the excelFilter)

All of them are described in detail below.

Setting and Configuring Filter

Setting a filter

A built-in filter is set by the content property of the header/footer attribute. Note that to add a filter to the header (footer), the header (footer) must be specified as an object or an array.

columns:[
  { id:"year", header:{ content:"{filtername}Filter" } },
  {
    id:"title",
    header:[
      { content:"{filtername}Filter" },
      "Title"
    ]
  }
]

If you need to create a **custom filter** (or some other custom element) for a header or you need to **change the way** a filter works, [go here](/docs/headers-footers#custom-header-and-footer-content).

Configuring filters PRO

This functionality is available for Pro filters only.

You can configure the control that is used in the grid header for filtering (richselect, datepicker, etc) with the inputConfig property.

For example, you can enable the tagMode feature for the multiComboFilter as follows:

{
  id:"year",
    header:[
      "Released", {
        content:"multiComboFilter", inputConfig:{ tagMode:true }
      }
     ]
}

Getting Options for Selection Filters

By default, the options for a selection filter (selectFilter, richSelectFilter, multiSelectFilter, multiComboFilter, and their server counterparts) are taken:

from the column values,
from the column collection/options,
from collection/options of the filter.

You can set collection/options in several ways just like for columns, and regardless of the way the options will be stored in a DataCollection.

{
  id:"year", header:[
      "Released", {
        content:"selectFilter", options:data_collection
      }
     ]
},
{
  id:"title", options:local_array, header:[
    "Film title", {
      content:"multiSelectFilter", options:"server/films/"
    }
  ]
}

If there is a collection for the column, but you want the filter to take its options from the column values, you can add an additional configuration property to the filter:

{
  id:"year", options:data_collection,
    header:[
      "Released", {
        content:"selectFilter", collect:{ visible:true }
      }
     ]
}

Filters Description

Text filter

Finds records that have the string typed into the text field in this column.

{ id:"title", header:[ "Film title", { content:"textFilter" } ] }

Server Filter

A text filter that works with backend. Retrieves the text from the text field and sends a request to the server to return filtered data.

{ id:"title", header:[ "Film title", { content:"serverFilter" } ] }

Request parameters are:

count - the number of data records to return. Its value depends on dynamic loading parameters, if they are set;
start - the ID to start from (0 - beginning). Its value depends on dynamic loading parameters, if they are set;
filter[column_name] - the name of the column for which filtering is performed. Its value is the text that the user entered in the filter input.

# find all films with 'the' in the title
data/films?count=50&start=0&filter[title]=the

If server-side sorting is enabled, data are both filtered and sorted on the server.

Select filter

Based on a standard HTML select input. Finds data records by comparing the values from the column to the selected option.

{ id:"title", header:[ "Film title",{ content:"selectFilter" } ] }

ServerSelect Filter

A select filter that works with backend. Gets the selected option and sends a request to server to return filtered data.

{ id:"title", header:[ "Film title", { content:"serverSelectFilter" } ] }

Request parameters are:

count - the number of data records to return. Its value depends on dynamic loading parameters, if any;
start - the ID of the data record to start from (0 - beginning). Its value depends on dynamic loading parameters, if any;
filter[column_name] - the name of the column (in brackets) for which filtering is performed. Its value is the option selected from the list.

If server-side sorting is enabled, data are both filtered and sorted on the server.

Number filter

This is a text filter used for columns with numbers. It finds data records by comparing values from the column to the typed number or condition. The user can filter numbers with comparison operators:

’=’ - equal to;
’>’ - greater than;
’<’ - less than;
’<=’ - less or equal;
’>=’ - greater or equal.

{ id:"year", header:[ "Released", { content:"numberFilter" } ] }

Date filter

This is a text filter used for date columns. It finds data records by comparing dates from the column to the typed date or condition. The user can filter data with the following comparison operators:

’>’ - greater than;
’<’ - less than;
’<=’ - less or equal;
’>=’ - greater or equal.

There are 3 ways you can input dates to the dateFilter:

‘yyyy’ - 4-digits year;
‘mm.yyyy’ - 2-digits month and 4-digits year separated by point;
‘dd.mm.yyyy’ - 2-digits day, 2-digits month and 4-digits year separated by points

{
  id:"year",
  header:[ "Released",{ content:"dateFilter"}],
  format:webix.i18n.dateFormatStr
}

Richselect Filter PRO

Finds data records by comparing the selected option with values from the column.

{ id:"year", header:["Released", { content:"richSelectFilter" }]}

ServerRichSelect Filter PRO

Gets the selected option and sends a request to a server to return filtered data.

{ id:"year",header:["Released", { content:"serverRichSelectFilter" }]}

Request parameters are:

count - the number of data records to return. Its value depends on dynamic loading parameters, if any;
start - the ID to start from (0 - beginning). Its value depends on dynamic loading parameters, if any;
filter[column_name] - the name of the column (in brackets) for which filtering is performed. Its value is the option selected in the dropdown list.

If server-side sorting is enabled, data are both filtered and sorted on a server.

Multiselect Filter PRO

The user can select several options from the dropdown list. The filter will find records by comparing the values from the column to selected options.

{ id:"year",header:["Released", { content:"multiSelectFilter" }]}

ServerMultiSelect Filter PRO

The user can select several options from the dropdown list. The filter gets selected options and sends a request to a server to return filtered data.

{ id:"year",header:["Released", { content:"serverMultiSelectFilter" }]}

Request parameters are:

count - the number of data records to return. Its value depends on dynamic loading parameters, if any;
start - the ID to start from (0 - beginning). Its value depends on dynamic loading parameters, if any;
filter[column_name] - the name of the column (in brackets) for which filtering is performed. Its value is a string with selected options.

If server-side sorting is enabled, data are both filtered and sorted on the server.

Multicombo Filter PRO

The user can type text and select several options from the list. The filter gets the selected options and finds records by comparing the values from the column with the selected options.

{ id:"year", header:["Released", { content:"multiComboFilter" }]  }

By default, the tagMode configuration property for this filter is disabled, i.e. the control shows only the number of the selected options.

You can enable the tagMode for the filter inside of the inputConfig property of the header configuration:

{
  id:"year",
  header:["Released", { content:"multiComboFilter", inputConfig:{tagMode:true} }]
}

In case a filter option contains some separator, e.g. a comma ("The Good, the Bad and the Ugly"), it may cause breaking of the filter.

To avoid such a break, use the separator property inside the filter object and set as its value any separator different from the one used in the option(s). For example, a semi-colon:

{ id:"title",header:["Film title", {content:"multiComboFilter", separator:";"}] }

ServerMultiCombo Filter PRO

The user can type text and select several options from the list. The filter gets the selected options and sends a request to a server to return filtered data.

{ id:"year",header:["Released", { content:"serverMultiComboFilter" }]}

Request parameters are:

count - the number of data records to return. Its value depends on dynamic loading parameters, if any;
start - the ID to start from (0 - beginning). Its value depends on dynamic loading parameters, if any;
filter[column_name] - the name of the column (in brackets) for which filtering is performed. Its value is a string with selected options.

If server-side sorting is enabled, data are both filtered and sorted on a server.

Datepicker Filter PRO

The user can select dates on a datepicker. The filter gets the selected date and finds records by comparing the dates in this column with the selected date.

{ id:"date", header:[ "Released", { content:"datepickerFilter" }],
  format:webix.i18n.dateFormatStr}

Daterange Filter PRO

The user can select date intervals on a daterangepicker. The filter gets the selected dates and finds records by comparing the dates in this column with the selected interval.

{ id:"date", header:["Deadline", { content:"dateRangeFilter"}],
  format:webix.i18n.dateFormatStr, width:200}

ServerDateRange Filter PRO

The user can select date intervals on a daterangepicker. The filter gets the selected dates and sends a request to a server to return filtered data.

{ id:"title", header:["Film title", {content:"serverDateRangeFilter"}],
  format:webix.i18n.dateFormatStr, width:200}

Request parameters are:

count - the number of data records to return. Its value depends on dynamic loading parameters, if any;
start - the ID to start from (0 - beginning). Its value depends on dynamic loading parameters, if any;
filter[column_name] - the name of the column (in brackets) for which filtering is performed. Its value is a string with the selected date interval.

If server-side sorting is enabled, data are both filtered and sorted on the server.

Excel Filter PRO

It’s Excel-like filter with customization possibility. Excel Filter allows setting the list of rules (depending on the defined mode) or exclude some data from filtering.

In the header line you can set:

content:“excelFilter” - defines the type of filter;
mode - defines the type of data the filter will be applied to (“text”, “number”, “date”);
template - defines the template of a filter;
filterConfig - defines the filter configuration, where you can put any Filter widget settings.

{ id:"year", header:[{text:"Released", content:"excelFilter", mode:"date"}],
  width:200,  sort:"date", format:webix.Date.dateToStr("%Y")
}

ServerExcel Filter PRO

The user can filter data, set the list of rules (depending on the defined mode) or exclude some data from filtering. The filter gets the set filtering rules and sends a request to a server to return the filtered data.

{ id:"year", header:[{text:"Released", content:"serverExcelFilter", mode:"date"}],
  width:200, sort:"date", format:webix.Date.dateToStr("%Y")
}

Request parameters are:

count - the number of data records to return. Its value depends on dynamic loading parameters, if any
start - the ID to start from (0 - beginning). Its value depends on dynamic loading parameters, if any
filter[column_name] - the name of the column (in brackets) filtering is performed for. Its value is a string with the filter value

If server-side sorting is enabled, data are both filtered and sorted on a server.

Filtering Logic

Each time the user starts to type text in a filter, DataGrid calls the filterByAll method and data are re-filtered (previous results aren’t preserved).

AND logic

By default, when there are filters in several columns, DataGrid applies the AND logic to them, i.e. the datagrid will display only the records that meet all criteria at once.

OR logic

If you want to apply the OR logic (to display records that meet at least one of the criteria), you should redefine the filterByAll() method. For example:

Implementing OR logic for filters

const grid = webix.grid({
  id:"grid",
  columns:[
    { id:"title", header:["Film title", {content:"textFilter"}] },
    { id:"year",  header:["Released",  {content:"selectFilter"}] },
        { id:"votes", header:"Votes" }
  ]
});

grid.filterByAll = function(){
  // gets filter values
  var title = this.getFilter("title").value;
  var year = this.getFilter("year").value;

  // unfilters the grid if values were not selected
  if (!(title || year)) return this.filter();

  // filters using OR logic
  this.filter(function(obj){
    return (obj.year == year) ||
      (obj.title.toLowerCase().indexOf(title) != -1);
  });
};

Custom Filtering Rules

You can change the default filtering pattern by redefining the compare function of the header(footer) attribute.

The function receives 3 parameters:

columnValue - a value from the column (the function checks values one by one);
filterValue - the value entered in the filter;
object - the object of the filter.

For example, to make DataGrid filtered only by the beginning of strings, define the function like this:

Filtering by the start letter of the column values

function startCompare(value, filter){
  value = value.toString().toLowerCase();
  filter = filter.toString().toLowerCase();
  return value.indexOf(filter) === 0;
}

webix.grid({
  columns:[
    {
      id:"title",
      header:[
        "Film title",
        {
          content:"textFilter",compare:startCompare
        }
      ]
    }
     ]
});

Preparing values for filtering

If you want to preprocess the input from the filter, redefine the prepare function of the filter in the header(footer) object. This function receives two parameters:

filterValue - the value entered in the filter;
filterObject - the object of the filter.

webix.grid({
  columns:[
    {
      id:"title",
      header:[
        "Film title",
        {
          content:"textFilter",
          prepare:function(filterValue, filterObject){
            return filterValue;
          },
          compare:function(cellValue, filterValue){
            return cellValue == filterValue;
          }
        }
      ]
    }
     ]
});

Filtering by multiple criteria entered via one input

The user can filter DataGrid by different columns using one input for this.

This can be done by:

Redefining the filterByAll() method;
Specifying an additional filtering rule.

Filtering by multiple criteria (by using method filterByAll)

const grid = webix.grid({
  id:"grid",
  columns:[
    { id:"rank",  header:["#", { content:"textFilter", colspan:3}] },
    { id:"title",  header:["Film title",""] },
    { id:"year",  header:["Released",""] },
  ]
});

grid.filterByAll = function(){
  // gets filter values
  var text = this.getFilter("rank").value.toString().toLowerCase();
  // unfilters for empty search text
  if (!text) return this.filter();

  // filters using OR logic
  this.filter(function(obj){
    return (obj.year == text) || (obj.title.toLowerCase().indexOf(text)!=-1);
  });
};

Filtering by multiple criteria (by specifying an additional filtering rule)

webix.grid({
  columns:[
    {
      id:"rank",
      header:[
        "#",
        { content:"textFilter", compare:oneForAll, colspan:3 }
      ]
    },
    { id:"title",  header:["Film title",""]},
    { id:"year",  header:["Release year",""]}
  ]
});

function oneForAll(value, filter, obj){
  var text = filter.toLowerCase();
  return (obj.year.toString().toLowerCase().indexOf(text) !== -1;) ||
    (obj.title.toLowerCase().indexOf(text) != -1);
};

HTML Inputs as Filters for DataGrid

Setting an HTML input as a datagrid filter

Create the input:

Setting a Custom Filter

<input type="text" id='myfilter'>

Add this input as a new type of filter using registerFilter:

const grid = webix.grid({  // component
    columns:[
      {id:"title", ...}
    ]
});

grid.registerFilter(
  document.getElementById("myfilter"),
  { columnId:"title" }, // column or data field to filter, must be unique to each filter
  {
    getValue:function(node){
      return node.value;
    },
    setValue:function(node, value){
      node.value = value;
    }
    }
);

Please, keep in mind that columnId must be unique to each filter, built-in or new. More details in registerFilter.

Custom Filtering with the filter() method

DataGrid has the filter() method for fully custom filtering.

Let’s create a text control and filter a grid by input into the control. onTimedKeyPress is the ideal event to start filtering:

Implementing a custom filter

const grid = webix.grid({
  id:"grid", autoConfig:true, data:some_data
});

grid.filter(function(obj){
  return obj.title.toLowerCase().indexOf(input) !== -1;
});

Find API

DataGrid API allows searching for the needed records easily with the help of its find method.

Unlike filtering, it doesn’t hide any records. It simply returns an array of rows that match the given criterion for further usage.

For instance, it allows highlighting the filtered data:

var value = "some input";
// res - array of found rows
var res = grid.find(function(obj){
  return obj.title.toLowerCase().indexOf(value) != -1;
});

grid.clearCss("marker", true)
for (var i = 0; i < res.length; i++)
  grid.addCss(res[i].id, "marker", true);
grid.refresh();

Related sample: "Find" API