Old Documentation

You are browsing documentation for an old version of Tabulator. Consider upgrading your project to Tabulator 6.3

Filtering Data

Overview
Filter Functions
Managing Filters
Initial Filter
Column Header Filters
Callbacks

Overview

Filter functionality is provided by the filter module

Tabulator allows you to filter the table data by any field in the data set.

To set a filter you need to call the setFilter method, passing the field you wish to filter, the comparison type and the value to filter for.

This function will replace any exiting filters on the table with the specified filters.

table.setFilter("age", ">", 10);

Filter Functions

Built In Filters

Tabulator comes with a number of filter comparison types including:

= - Displays only rows with data that is the same as the filter
< - displays rows with a value less than the filter value
<= - displays rows with a value less than or qual to the filter value
> - displays rows with a value greater than the filter value
>= - displays rows with a value greater than or qual to the filter value
!= - displays rows with a value that is not equal to the filter value
like - displays any rows with data that contains the specified string anywhere in the specified field. (case insensitive)
in - displays any rows with a value in the filter value array passed to the filter (eg ["steve", "bob", "jim"], values must be of the same type as they are in the array
regex - displays rows that match a provided regex

If you wish to apply multiple filters then you can pass an array of filter objects to this function, the data will then have to pass all filters to be displayed in the table.

table.setFilter([
    {field:"age", type:">", value:52}, //filter by age greater than 52
    {field:"height", type:"<", value:142}, //and by height less than 142
    {field:"name", type:"in", value:["steve", "bob", "jim"]}, //name must be steve, bob or jim
]);

Filters will remain in effect until they are cleared, including during setData calls.

Custom Filter Functions

If you want to perform a more complicated filter then you can pass a callback function to the setFilter method, you can also pass an optional second argument, an object with parameters to be passed to the filter function.

function customFilter(data, filterParams){
    //data - the data for the row being filtered
    //filterParams - params object passed to the filter

    return data.name == "bob" && data.height < filterParams.height; //must return a boolean, true if it passes the filter.
}

table.setFilter(customFilter, {height:3});

Complex Filtering

The filtering example above shows how to apply a series of filters to some table data and show only the data where all the filters are matched, but what if you want to use an OR type comparison.

To do this you can put an array of filters inside your filter array, and any filters in this second array will use an OR comparison type.

The example below applies a filter that will let through rows with a age of greater than 52 AND (either a height of less than 142 OR with the name steve)

table.setFilter([
    {field:"age", type:">", value:52}, //filter by age greater than 52
    [
        {field:"height", type:"<", value:142}, //with a height of less than 142
        {field:"name", type:"=", value:"steve"}, //or a name of steve
    ]
]);

You can nest OR filter arrays several levels deep to build up complex filters.

Managing Filters

There are a number of additional methods that can be called to customise your filtering experience

Add Filter to Existing Filters

If you want to add another filter to the existing filters then you can call the addFilter function:

table.addFilter("age", ">", 22);

Remove One of Many Existing Filters

If you want to remove one filter from the current list of filters you can use the removeFilter function:

table.removeFilter("age", ">", 22);

Get Current Filters

You can retrieve an array of the current programtic filters using the getFilters function, this will not include any of the header filters:

var filters = table.getFilters();

This will return an array of filter objects

[
    {field:"age", type:">", value:52}, //filter by age greater than 52
    {field:"height", type:"<", value:142}, //and by height less than 142
]

To include header filters in the returend array pass an option argument of true to the getFilters function:

var allFilters = table.getFilters(true);

Get Header Filters

If you just want to retrieve the current header filters, you can use the getHeaderFilters function:

var headerFilters = table.getHeaderFilters();

Clear All Filters

To remove all filters from the table, use the clearFilter function.

table.clearFilter();

This will clear all programmatically set filters, if you wisht to clear all header filters as well pass an argument of true to this function.

table.clearFilter(true);

Clear Header Filters

To remove just the header filters, leaving the programatic filters in place, use the clearHeaderFilter function.

table.clearHeaderFilter();

Initial Filter

When the table is first created it can be defined with an initial set of filters. These can be set using the initialFilter option. This will take the same filter array as the setFilter function. (see Filter Functions for more details)

var table = new Tabulator("#example-table", {
    initialFilter:[
        {field:"color", type:"=", value:"red"}
    ],
});

Header Filtering

Header filters are also dependent on the edit module

Is is possible to filter the table data directly from the column headers, by setting the headerFilter parameter in the column definition object for that column.

{title:"Name", field:"name", headerFilter:true} //show header filter matching the cells editor

Setting this parameter to true will cause an editor element matching the columns editor type to be displayed in the header below the column title, and will allow the user to filter data in the table by values in that column. The editor will be chosen using the same rules as the editor parameter, for more information on this see the Manipulating Data section.

Alternatively you can pass a string to this parameter containing any of the standard editors listed in the Manipulating Data section

{title:"Name", field:"name", headerFilter:"input"} //show headerFilter using "input" editor

You can also pass a custom editor function to this parameter in the same way as you would for column editor. For more information see the Manipulating Data section.

You can pass an optional additional parameter with the header filter, headerFilterParams that should contain an object with additional information for configuring the header filter element. This will be passed to the editor in the column header instead of the editorParams property.

{title:"Name", field:"name", headerFilter:"input", headerFilterParams:{initial:"Steve Bobberson"}} //show headerFilter using "input" editor

Params Lookup Function

If you want to dynamically generate the headerFilterParams at the time the header filter is created, you can pass a function into the property that should return the params object.

//define lookup function
function paramLookup(cell){
    //do some processing and return the param object
    return {param1:"green"};
}

//column definition
{title:"Name", field:"name", headerFilter:"input", headerFilterParams:paramLookup}

Note: At present, the progress and star editors are not available as header filters.

Header Filters and Programmatic Filters

Header filters and programatic filters can be set independently allowing you to use a header filter to further restrict the rows shown in an already filtered data set.

Real Time Filtering

If an input element is used as the filter element, then then the table will be filtered in real time as the user types in the input element. To prevent exessive redrawing of the table Tabulator will wait 300 milliseconds after the user has finished typing before triggering the filter, this ensures that the table is not redrawn for every character typed by the user.

Note: If the input has a type attribute value of text it will be automatically changed to search to give the user the option to clear the input text.

Empty Header Filters

By default Tabulator will clear the filter when it considers the header filter value to be empty, in the case of most filters that is if the value is undefined, null, or "", or in the case of check boxes that is if the value is not either true or false.

If you are using a custom filter or want to alter what an existing filter considers empty, you can pass a function to the headerFilterEmptyCheck column definition property. This function will be passed in the value of the filter as an argument and should return a boolean where true represents an empty filter

{title:"Allowed", field:"allowed", headerFilter:"tick", headerFilterEmptyCheck:function(value){
    return !value; //only filter when the value is true
}},

Filter Comparison Types

By default Tabulator will try and match the comparison type to the type of element used for the header filter.

Standard input elements will use the "like" filter, this allows for the matches to be displayed as the user types.

For all other element types (select boxes, check boxes, input elements of type number) an "=" filter type is used.

If you want to specify the type of filter used you can pass it to the headerFilterFunc option in the column definition object. This will take any of the standard filters outlined above or a custom function:

{title:"Age", field:"age", headerFilter:"input", headerFilterPlaceholder:"Max Age", headerFilterFunc:"<="} //show only rows with an age less than or equal the entered value

When using a custom filter function for a header filter, the arguments passed to the function will be slightly different from a normal custom filter function

function customHeaderFilter(headerValue, rowValue, rowData, filterParams){
    //headerValue - the value of the header filter element
    //rowValue - the value of the column in this row
    //rowData - the data for the row being filtered
    //filterParams - params object passed to the headerFilterFuncParams property

    return rowData.name == filterParams.name && rowValue < headerValue; //must return a boolean, true if it passes the filter.
}

//column definition object in table constructor
{title:"Age", field:"age", headerFilter:"input", headerFilterPlaceholder:"Max Age", headerFilterFunc:customHeaderFilter, headerFilterFuncParams:{name:"bob"}}

As the above example demostrates it is possible to pass additional parameters to the custom filter function by passing an object to the headerFilterFuncParams option in the column definition.

{title:"Age", field:"age", headerFilter:"input", headerFilterPlaceholder:"Max Age", headerFilterFunc:customHeaderFilter, headerFilterFuncParams:{name:"bob"}}

Placeholder Text

The default placeholder text used for input elements can be set using the headerFilterPlaceholder option in the table definition

var table = new Tabulator("#example-table", {
    headerFilterPlaceholder:"filter data...", //set column header placeholder text
});

To set the placeholder text on a per column basis you can use the headerFilterPlaceholder option in the column's definition object.

var table = new Tabulator("#example-table", {
    headerFilterPlaceholder:"filter data...", //set column header placeholder text
    columns:[
        {title:"Name", field:"name", headerFilter:true, headerFilterPlaceholder:"Find a Person..."} //set placeholder text on name column header filter
    ]
});

Set Header Filter Value

You can programmatically set the header filter value of a column by calling the setHeaderFilterValue function, This function takes any of the standard column component look up options as its first parameter, with the value for the header filter as the second option

table.setHeaderFilterValue("name", "Steve"); //set header filter for name column to  "steve"

Focus On Header Filter

You can programmatically set the focus on a header filter element by calling the setHeaderFilterFocus function, This function takes any of the standard column component look up options as its first parameter

table.setHeaderFilterFocus("name"); //focus on the header filter for the name column

Callbacks

A range of callbacks are available for tracking progress of filtering. See the Filter Callbacks section for more information.

Version 6.3 Released!

Filtering Data

Overview Demo

Filter Functions

Built In Filters

Custom Filter Functions

Complex Filtering

Managing Filters

Add Filter to Existing Filters

Remove One of Many Existing Filters

Get Current Filters

Get Header Filters

Clear All Filters

Clear Header Filters

Initial Filter

Header Filtering Demo

Params Lookup Function

Header Filters and Programmatic Filters

Real Time Filtering

Empty Header Filters

Filter Comparison Types

Placeholder Text

Set Header Filter Value

Focus On Header Filter

Callbacks

Overview

Header Filtering